@beastmode-develeap/beastmode 0.1.213 → 0.1.215

package/dist/web/board.html

@@ -15,7 +15,7 @@
 }
 </script>
 <!--BOARD_DATA-->
-<script>window.__BUILD_STAMP__ = "20260509-151332-bb5cfbc";</script>
+<script>window.__BUILD_STAMP__ = "20260509-231045-f21d1ff";</script>
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
@@ -2184,6 +2184,95 @@ input[type="range"]::-webkit-slider-thumb {
 .filter-toggle:hover { border-color: var(--text-muted); color: var(--text); }
 .filter-toggle.active { border-color: var(--accent); color: var(--accent); background: var(--accent-subtle); }
 
+/* Sort toggle button — mirrors filter-toggle */
+.sort-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 0 14px;
+  height: 36px;
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  color: var(--text-secondary);
+  font-size: 13px;
+  font-family: var(--font-sans);
+  cursor: pointer;
+  transition: all 0.15s;
+  white-space: nowrap;
+  position: relative;
+}
+.sort-toggle:hover { border-color: var(--text-muted); color: var(--text); }
+.sort-toggle.active { border-color: var(--accent); color: var(--accent); background: var(--accent-subtle); }
+
+.sort-active-label {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--accent);
+  margin-left: 2px;
+}
+
+/* Sort dropdown */
+.sort-dropdown {
+  position: absolute;
+  top: 100%;
+  right: 0;
+  margin-top: 4px;
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+  z-index: 100;
+  min-width: 180px;
+  padding: 4px;
+}
+
+.sort-options {
+  display: flex;
+  flex-direction: column;
+}
+
+.sort-option {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 8px 12px;
+  background: none;
+  border: none;
+  color: var(--text-secondary);
+  font-size: 13px;
+  font-family: var(--font-sans);
+  cursor: pointer;
+  border-radius: var(--radius-sm);
+  transition: background 0.1s;
+  width: 100%;
+  text-align: left;
+}
+.sort-option:hover { background: var(--bg-hover); color: var(--text); }
+.sort-option.active { color: var(--accent); font-weight: 600; }
+
+.sort-dir-icon {
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--accent);
+}
+
+.sort-clear {
+  display: block;
+  width: 100%;
+  padding: 8px 12px;
+  background: none;
+  border: none;
+  border-top: 1px solid var(--border);
+  color: var(--text-muted);
+  font-size: 12px;
+  font-family: var(--font-sans);
+  cursor: pointer;
+  text-align: center;
+  margin-top: 4px;
+}
+.sort-clear:hover { color: var(--danger); }
+
 .view-toggle {
   display: inline-flex;
   border: 1px solid var(--border);
@@ -3474,6 +3563,167 @@ input[type="range"]::-webkit-slider-thumb {
 }
 .btn-secondary:hover { background: var(--surface-elevated); border-color: var(--text-muted); }
 
+/* ================================================================
+   ONBOARDING TOUR & CHECKLIST
+   ================================================================ */
+
+.tour-backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.6);
+  z-index: 9000;
+  animation: fadeIn 0.2s ease;
+}
+.tour-spotlight {
+  position: fixed;
+  z-index: 9001;
+  border-radius: 8px;
+  box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.6);
+  pointer-events: none;
+  transition: top 0.3s ease, left 0.3s ease, width 0.3s ease, height 0.3s ease;
+}
+.tour-tooltip {
+  position: fixed;
+  z-index: 9002;
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 24px;
+  max-width: 380px;
+  width: 90vw;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+  animation: slideUp 0.25s ease;
+}
+.tour-tooltip h3 {
+  font-size: 18px;
+  font-weight: 600;
+  color: var(--text);
+  margin: 0 0 8px 0;
+}
+.tour-tooltip p {
+  font-size: 14px;
+  color: var(--text-secondary);
+  line-height: 1.5;
+  margin: 0 0 20px 0;
+}
+.tour-step-indicator {
+  display: flex;
+  gap: 6px;
+  margin-bottom: 16px;
+}
+.tour-step-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--border);
+}
+.tour-step-dot.active {
+  background: var(--accent);
+}
+.tour-actions {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+.tour-actions .tour-skip {
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  font-size: 13px;
+  font-family: var(--font-sans);
+  text-decoration: underline;
+  padding: 0;
+}
+.tour-actions .tour-skip:hover { color: var(--text); }
+.tour-actions-right { display: flex; gap: 8px; }
+
+.onboarding-checklist {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 20px;
+  margin-bottom: 16px;
+}
+.onboarding-checklist h3 {
+  font-size: 15px;
+  font-weight: 600;
+  color: var(--text);
+  margin: 0 0 4px 0;
+}
+.onboarding-checklist .subtitle {
+  font-size: 13px;
+  color: var(--text-muted);
+  margin: 0 0 16px 0;
+}
+.checklist-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 0;
+  font-size: 14px;
+  color: var(--text-secondary);
+}
+.checklist-item.completed {
+  color: var(--text-muted);
+  text-decoration: line-through;
+}
+.checklist-check {
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  border: 2px solid var(--border);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  font-size: 12px;
+  line-height: 1;
+}
+.checklist-check.done {
+  background: var(--success);
+  border-color: var(--success);
+  color: #fff;
+}
+.onboarding-progress {
+  height: 4px;
+  background: var(--border);
+  border-radius: 2px;
+  margin: 16px 0 12px;
+  overflow: hidden;
+}
+.onboarding-progress-fill {
+  height: 100%;
+  background: var(--accent);
+  border-radius: 2px;
+  transition: width 0.4s ease;
+}
+.onboarding-tour-btn {
+  width: 100%;
+  margin-top: 12px;
+}
+.onboarding-dismiss {
+  display: block;
+  text-align: center;
+  margin-top: 8px;
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  font-size: 12px;
+  cursor: pointer;
+  font-family: var(--font-sans);
+  width: 100%;
+  padding: 4px 0;
+}
+.onboarding-dismiss:hover { color: var(--text); }
+
+@media (max-width: 900px) {
+  .tour-tooltip {
+    max-width: 90vw;
+    padding: 20px;
+  }
+}
+
 /* ================================================================
    COSTS PAGE
    ================================================================ */
@@ -3852,6 +4102,7 @@ function Icon({ name, size = 18, className = '' }) {
     lightbulb: html`<path d="M8 1a5 5 0 00-3 9c.5.6.8 1.2 1 1.8V13h4v-1.2c.2-.6.5-1.2 1-1.8A5 5 0 008 1z"/><line x1="6" y1="13.5" x2="10" y2="13.5"/><line x1="6.5" y1="15" x2="9.5" y2="15"/>`,
     help: html`<circle cx="8" cy="8" r="6.5"/><path d="M6 6.5a2 2 0 013.7 1c0 1.5-1.7 1.5-1.7 3"/><circle cx="8" cy="12" r="0.5" fill="currentColor" stroke="none"/>`,
     filter: html`<polygon points="1.5,2 14.5,2 9.5,8.5 9.5,13 6.5,14.5 6.5,8.5"/>`,
+    'arrow-up-down': html`<path d="M4 6l4-4 4 4"/><path d="M4 10l4 4 4-4"/>`,
     costs: html`<circle cx="8" cy="8" r="6.5"/><path d="M8 3.5v1m0 7v1M6 10.5c0 .8.9 1.5 2 1.5s2-.7 2-1.5S9.1 9 8 9s-2-.7-2-1.5S6.9 6 8 6s2 .7 2 1.5"/>`,
   };
 
@@ -3953,7 +4204,7 @@ function Sidebar({ currentHash, factoryName, theme, onToggleTheme, selectedProje
   ];
 
   return html`
-    <aside class=${'sidebar' + (mobileOpen ? ' open' : '')}>
+    <aside class=${'sidebar' + (mobileOpen ? ' open' : '')} data-tour="sidebar">
       <div class="sidebar-brand">
         <svg class="brand-logo-svg" viewBox="0 0 400 320" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="BeastMode — Dark Factory">
           <g transform="translate(200,130)">
@@ -4003,7 +4254,8 @@ function Sidebar({ currentHash, factoryName, theme, onToggleTheme, selectedProje
         ${links.map(link => html`
           <li key=${link.path}>
             <a href=${link.path}
-               class=${currentHash === link.path || (link.path !== '#/' && currentHash.startsWith(link.path)) ? 'active' : ''}>
+               class=${currentHash === link.path || (link.path !== '#/' && currentHash.startsWith(link.path)) ? 'active' : ''}
+               data-tour=${link.path === '#/help' ? 'help-link' : null}>
               <${Icon} name=${link.icon} />
               ${link.label}
             </a>
@@ -4044,11 +4296,15 @@ function statusBadgeClass(status) {
 function DashboardPage({ selectedProject, onProjectChange }) {
   const [status, setStatus] = useState(null);
   const [recentItems, setRecentItems] = useState([]);
+  const [allItems, setAllItems] = useState([]);
   const [runs, setRuns] = useState([]);
   const [projects, setProjects] = useState([]);
   const [runnerData, setRunnerData] = useState({ count: 0, offline: 0 });
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState(null);
+  const [onboardingDismissed, setOnboardingDismissed] = useState(() => {
+    try { return !!localStorage.getItem('beastmode-onboarding-dismissed'); } catch (_) { return false; }
+  });
 
   useEffect(() => {
     function fetchDashboard() {
@@ -4059,7 +4315,10 @@ function DashboardPage({ selectedProject, onProjectChange }) {
         api('GET', '/api/projects').catch(() => ({ projects: [] })),
       ]).then(([s, boardData, runsData, projectsData]) => {
         setStatus(s);
-        const sorted = (boardData.items || [])
+        const allBoardItems = boardData.items || [];
+        setAllItems(allBoardItems);
+        const sorted = allBoardItems
+          .slice()
           .sort((a, b) => new Date(normalizeDt(b.updated_at || b.created_at) || 0) - new Date(normalizeDt(a.updated_at || a.created_at) || 0))
           .slice(0, 10);
         setRecentItems(sorted);
@@ -4246,6 +4505,48 @@ function DashboardPage({ selectedProject, onProjectChange }) {
         </div>
 
         <div class="page-dashboard-sidebar">
+          ${!onboardingDismissed && (() => {
+            const hasProject = projects.length >= 1;
+            const hasItem = allItems.length >= 1;
+            const hasDone = allItems.some(i => (i.status || '').toLowerCase() === 'done');
+            const checks = [
+              { label: 'Add a project', done: hasProject },
+              { label: 'Create your first task', done: hasItem },
+              { label: 'Complete a task', done: hasDone },
+            ];
+            const completedCount = checks.filter(c => c.done).length;
+            const allDone = completedCount === checks.length;
+            const dismiss = () => {
+              try { localStorage.setItem('beastmode-onboarding-dismissed', 'true'); } catch (_) {}
+              setOnboardingDismissed(true);
+            };
+            return html`
+              <div class="onboarding-checklist" data-testid="onboarding-checklist">
+                <h3>Getting Started</h3>
+                <p class="subtitle">Complete these steps to get up and running</p>
+                ${allDone ? html`
+                  <p style="font-size:14px;color:var(--success);font-weight:600;margin:8px 0 0;" data-testid="onboarding-congrats">
+                    You're all set! BeastMode is ready to build.
+                  </p>
+                ` : html`
+                  <div class="onboarding-progress">
+                    <div class="onboarding-progress-fill" style=${'width:' + ((completedCount / checks.length) * 100) + '%'}></div>
+                  </div>
+                  ${checks.map((c, i) => html`
+                    <div key=${i} class=${'checklist-item' + (c.done ? ' completed' : '')} data-testid=${'checklist-item-' + i}>
+                      <div class=${'checklist-check' + (c.done ? ' done' : '')}>${c.done ? '✓' : ''}</div>
+                      <span>${c.label}</span>
+                    </div>
+                  `)}
+                  <button class="btn btn-primary btn-pill onboarding-tour-btn" data-testid="onboarding-tour-btn"
+                          onClick=${() => { if (typeof window.__bmStartTour === 'function') window.__bmStartTour(); }}>
+                    Take the guided tour
+                  </button>
+                `}
+                <button class="onboarding-dismiss" data-testid="onboarding-dismiss" onClick=${dismiss}>Dismiss</button>
+              </div>
+            `;
+          })()}
           <div class="card">
             <div class="card-header">
               <h3>Recent Activity</h3>
@@ -5895,8 +6196,7 @@ function PipelineView({
   selectedProject,
   setSelectedItem,
   deleteItem,
-  columnSorts,
-  cycleSort,
+  globalSort,
   sortColumnItems,
   costsByItem,
   envVerifyByItem,
@@ -5995,8 +6295,7 @@ function PipelineView({
               ${columns.map(colId => {
                 const meta = getColumnMeta(colId);
                 const rawColItems = laneItemList.filter(item => getItemColumn(item, columns) === colId);
-                const colItems = sortColumnItems(rawColItems, columnSorts[colId] || '');
-                const sortMode = columnSorts[colId] || '';
+                const colItems = sortColumnItems(rawColItems, globalSort);
                 return html`
                   <div class="pipeline-column"
                        data-testid=${'pipeline-col-' + colId}
@@ -6007,9 +6306,8 @@ function PipelineView({
                        onDrop=${e => onDrop(e, colId)}>
                     <div class="pipeline-column-header"
                          style=${'--col-color: ' + meta.color}
-                         title=${meta.tooltip}
-                         onClick=${() => cycleSort(colId)}>
-                      <span>${meta.label}${sortMode && html`<span class="sort-indicator">${sortMode === 'priority' ? '\u25BC' : '\u25B2'}</span>`}</span>
+                         title=${meta.tooltip}>
+                      <span>${meta.label}</span>
                       <span class=${'kanban-count' + (colItems.length === 0 ? ' kanban-count-zero' : '')}>${colItems.length}</span>
                     </div>
                     <div class="pipeline-column-items">
@@ -6260,7 +6558,14 @@ function BoardPage({ selectedProject }) {
     const allKeys = ((window.PIPELINE_CONFIG && window.PIPELINE_CONFIG.swimlanes) || []).map(s => s.key);
     return new Set(allKeys);
   });
-  const [columnSorts, setColumnSorts] = useState({});
+  const [globalSort, setGlobalSort] = useState(() => {
+    try {
+      const saved = localStorage.getItem('beastmode-sort-mode');
+      if (saved) return JSON.parse(saved);
+    } catch {}
+    return { field: '', direction: 'asc' };
+  });
+  const [sortOpen, setSortOpen] = useState(false);
   const [epicCollapseKey, setEpicCollapseKey] = useState(0);
   const [costsByItem, setCostsByItem] = useState({});
   const [envVerifyByItem, setEnvVerifyByItem] = useState({});
@@ -6699,6 +7004,25 @@ function BoardPage({ selectedProject }) {
     } catch {}
   }, [activeSwimlanesSet]);
 
+  // Persist sort preference to localStorage whenever it changes.
+  useEffect(() => {
+    localStorage.setItem('beastmode-sort-mode', JSON.stringify(globalSort));
+  }, [globalSort]);
+
+  // Close sort dropdown when clicking outside.
+  useEffect(() => {
+    if (!sortOpen) return;
+    const handler = (e) => {
+      const dropdown = document.querySelector('.sort-dropdown');
+      const toggle = document.querySelector('[data-testid="sort-toggle"]');
+      if (dropdown && !dropdown.contains(e.target) && toggle && !toggle.contains(e.target)) {
+        setSortOpen(false);
+      }
+    };
+    document.addEventListener('click', handler, true);
+    return () => document.removeEventListener('click', handler, true);
+  }, [sortOpen]);
+
   // Expose swimlane state for external scenario verification.
   useEffect(() => {
     const swimlanes = (window.PIPELINE_CONFIG && window.PIPELINE_CONFIG.swimlanes) || [];
@@ -6780,28 +7104,32 @@ function BoardPage({ selectedProject }) {
   const activeFilterCount = _baseFilterCount + (_swimlaneFilterActive ? 1 : 0);
 
   // ── Column sorting ──
+  const SORT_LABELS = {
+    priority: 'Priority',
+    name: 'Name',
+    created: 'Created',
+    updated: 'Updated',
+    status_age: 'Time in Status',
+  };
   const PRIORITY_ORDER = { 'Critical': 0, 'High': 1, 'Medium': 2, 'Low': 3, '': 4 };
-  const sortColumnItems = (colItems, mode) => {
-    if (!mode) return colItems; // default: keep API order (newest first)
+  const sortColumnItems = (colItems, sort) => {
+    if (!sort || !sort.field) return colItems;
+    const dir = sort.direction === 'desc' ? -1 : 1;
     const sorted = [...colItems];
-    if (mode === 'priority') {
-      sorted.sort((a, b) => (PRIORITY_ORDER[a.priority || ''] ?? 4) - (PRIORITY_ORDER[b.priority || ''] ?? 4));
-    } else if (mode === 'name') {
-      sorted.sort((a, b) => (a.name || a.title || '').localeCompare(b.name || b.title || ''));
+    if (sort.field === 'priority') {
+      sorted.sort((a, b) => dir * ((PRIORITY_ORDER[a.priority || ''] ?? 4) - (PRIORITY_ORDER[b.priority || ''] ?? 4)));
+    } else if (sort.field === 'name') {
+      sorted.sort((a, b) => dir * (a.name || a.title || '').localeCompare(b.name || b.title || ''));
+    } else if (sort.field === 'created') {
+      sorted.sort((a, b) => dir * ((a.created_at || '').localeCompare(b.created_at || '')));
+    } else if (sort.field === 'updated') {
+      sorted.sort((a, b) => dir * ((a.updated_at || '').localeCompare(b.updated_at || '')));
+    } else if (sort.field === 'status_age') {
+      sorted.sort((a, b) => dir * ((a.status_changed_at || a.updated_at || '').localeCompare(b.status_changed_at || b.updated_at || '')));
     }
     return sorted;
   };
 
-  const cycleSort = (colId) => {
-    setColumnSorts(prev => {
-      const current = prev[colId] || '';
-      const next = current === '' ? 'priority' : current === 'priority' ? 'name' : '';
-      const copy = { ...prev };
-      if (next) copy[colId] = next; else delete copy[colId];
-      return copy;
-    });
-  };
-
   // Unique project IDs and parent epics for filter dropdowns
   const uniqueProjects = [...new Set(items.map(i => i.project_id).filter(Boolean))];
   const uniqueEpics = [...new Set(items.map(i => i.parent_epic).filter(Boolean))].map(String);
@@ -6864,7 +7192,7 @@ function BoardPage({ selectedProject }) {
 
       ${error && html`<div class="error-msg">${error}</div>`}
 
-      <div class="board-header-row">
+      <div class="board-header-row" data-tour="board-header">
         <div class="board-stats-bar">
           <span class="stat-label">${viewMode === 'pipeline' ? 'Pipeline' : 'Board'}</span>
           <span class="stat-item"><strong>${totalItems}</strong>${isFiltered ? '/' + items.length : ''} total</span>
@@ -6887,7 +7215,47 @@ function BoardPage({ selectedProject }) {
           ${activeFilterCount > 0 && html`<span class="filter-active-count">${activeFilterCount}</span>`}
         </button>
 
-        <button class="btn btn-primary" onClick=${() => setShowCreateDialog(true)}>
+        <div style="position: relative;">
+          <button class=${'sort-toggle' + (sortOpen || globalSort.field ? ' active' : '')}
+                  onClick=${() => setSortOpen(v => !v)}
+                  data-testid="sort-toggle">
+            <${Icon} name="arrow-up-down" size=${13} />
+            Sort
+            ${globalSort.field && html`<span class="sort-active-label">${SORT_LABELS[globalSort.field]}</span>`}
+          </button>
+          ${sortOpen && html`
+            <div class="sort-dropdown" data-testid="sort-dropdown">
+              <div class="sort-options">
+                ${Object.entries(SORT_LABELS).map(([key, label]) => html`
+                  <button key=${key}
+                          class=${'sort-option' + (globalSort.field === key ? ' active' : '')}
+                          data-testid=${'sort-option-' + key}
+                          onClick=${() => {
+                            if (globalSort.field === key) {
+                              setGlobalSort(s => ({ ...s, direction: s.direction === 'asc' ? 'desc' : 'asc' }));
+                            } else {
+                              const defaultDir = (key === 'created' || key === 'updated') ? 'desc' : 'asc';
+                              setGlobalSort({ field: key, direction: defaultDir });
+                            }
+                          }}>
+                    <span>${label}</span>
+                    ${globalSort.field === key && html`
+                      <span class="sort-dir-icon">${globalSort.direction === 'asc' ? '↑' : '↓'}</span>
+                    `}
+                  </button>
+                `)}
+              </div>
+              ${globalSort.field && html`
+                <button class="sort-clear" data-testid="sort-clear"
+                        onClick=${() => { setGlobalSort({ field: '', direction: 'asc' }); setSortOpen(false); }}>
+                  Clear sort
+                </button>
+              `}
+            </div>
+          `}
+        </div>
+
+        <button class="btn btn-primary" data-tour="add-item" onClick=${() => setShowCreateDialog(true)}>
           <${Icon} name="plus" size=${14} />
           New Task
         </button>
@@ -6984,8 +7352,7 @@ function BoardPage({ selectedProject }) {
             selectedProject=${selectedProject}
             setSelectedItem=${setSelectedItem}
             deleteItem=${deleteItem}
-            columnSorts=${columnSorts}
-            cycleSort=${cycleSort}
+            globalSort=${globalSort}
             sortColumnItems=${sortColumnItems}
             costsByItem=${costsByItem}
             envVerifyByItem=${envVerifyByItem}
@@ -7020,15 +7387,14 @@ function BoardPage({ selectedProject }) {
             if (col.also && col.also.includes(i.status)) return true;
             return false;
           });
-          const colItems = sortColumnItems(rawColItems, columnSorts[col.id] || '');
-          const sortMode = columnSorts[col.id] || '';
+          const colItems = sortColumnItems(rawColItems, globalSort);
           return html`
             <div class="kanban-column" key=${col.id}
                  onDragOver=${e => onDragOver(e, col.id)}
                  onDragLeave=${onDragLeave}
                  onDrop=${e => onDrop(e, col.id)}>
-              <div class="kanban-column-header" style=${'--col-color: ' + col.color} title=${col.tooltip} onClick=${() => cycleSort(col.id)}>
-                <span>${col.label}${sortMode && html`<span class="sort-indicator">${sortMode === 'priority' ? '\u25BC' : '\u25B2'}</span>`}</span>
+              <div class="kanban-column-header" style=${'--col-color: ' + col.color} title=${col.tooltip}>
+                <span>${col.label}</span>
                 <span class=${'kanban-count' + (colItems.length === 0 ? ' kanban-count-zero' : '')}>${colItems.length}</span>
               </div>
               <div class="kanban-items">
@@ -8877,10 +9243,33 @@ function HooksTab() {
 // ================================================================
 
 function HelpPage() {
+  const startTour = () => {
+    navigate('#/board');
+    setTimeout(() => {
+      if (typeof window.__bmStartTour === 'function') window.__bmStartTour();
+    }, 300);
+  };
   return html`
     <div>
       <h2 style="margin:0 0 24px;font-size:22px;font-weight:700;color:var(--text-primary);">Help & Documentation</h2>
 
+      <div style="margin-bottom: 24px; padding: 16px; background: var(--surface-elevated);
+                  border: 1px solid var(--border); border-radius: 8px;
+                  display: flex; align-items: center; justify-content: space-between;"
+           data-testid="help-tour-card">
+        <div>
+          <div style="font-weight: 600; color: var(--text); margin-bottom: 4px;">
+            Interactive Tour
+          </div>
+          <div style="font-size: 13px; color: var(--text-muted);">
+            Walk through the key features of BeastMode step by step.
+          </div>
+        </div>
+        <button class="btn btn-primary" data-testid="help-start-tour" onClick=${startTour}>
+          Start Tour
+        </button>
+      </div>
+
       <div class="settings-section">
         <h3>Getting Started</h3>
         <div style="line-height:1.8;color:var(--text-secondary);">
@@ -10706,6 +11095,211 @@ function FactoryStatusBar() {
 // App Root
 // ================================================================
 
+// ================================================================
+// Onboarding Tour
+// ================================================================
+
+const TOUR_STEPS = [
+  {
+    target: null,
+    title: 'Welcome to BeastMode',
+    body: "BeastMode turns your ideas into working software — describe what you want in plain language, and the pipeline writes the spec, code, and tests. Let's take a quick tour.",
+    placement: 'center',
+  },
+  {
+    target: '[data-tour="sidebar"]',
+    title: 'Navigation',
+    body: 'Use the sidebar to move between pages. The Board is where your tasks live. The Dashboard shows factory health and stats.',
+    placement: 'right',
+  },
+  {
+    target: '[data-tour="board-header"]',
+    title: 'Your Task Board',
+    body: 'Tasks flow through the pipeline from left to right: Ready → Working on it → Review → Done. BeastMode handles each stage automatically.',
+    placement: 'bottom',
+  },
+  {
+    target: '[data-tour="add-item"]',
+    title: 'Create a Task',
+    body: 'Click here to create a new task. Describe what you want to build — BeastMode writes the spec, plans the work, and implements it.',
+    placement: 'bottom-start',
+  },
+  {
+    target: '[data-tour="help-link"]',
+    title: 'Need Help?',
+    body: 'Visit the Help page anytime for guides on task types, pipeline stages, and troubleshooting tips.',
+    placement: 'right',
+  },
+  {
+    target: null,
+    title: "You're Ready!",
+    body: 'Start by creating your first task. BeastMode takes it from there. You can restart this tour anytime from the Help page.',
+    placement: 'center',
+  },
+];
+
+function OnboardingTour() {
+  const [currentStep, setCurrentStep] = useState(null);
+  const [targetRect, setTargetRect] = useState(null);
+
+  // Auto-launch on first visit.
+  useEffect(() => {
+    let cancelled = false;
+    try {
+      if (localStorage.getItem('beastmode-tour-completed')) return;
+    } catch (_) { return; }
+    if (!location.hash || location.hash === '#/' || location.hash === '#') {
+      navigate('#/board');
+    }
+    const t = setTimeout(() => {
+      if (!cancelled) setCurrentStep(0);
+    }, 600);
+    return () => { cancelled = true; clearTimeout(t); };
+  }, []);
+
+  // Expose manual launcher globally for Dashboard checklist + Help page button.
+  useEffect(() => {
+    window.__bmStartTour = () => setCurrentStep(0);
+    return () => { try { delete window.__bmStartTour; } catch (_) {} };
+  }, []);
+
+  // Recalculate target rect on step change and on resize.
+  useEffect(() => {
+    if (currentStep === null) {
+      setTargetRect(null);
+      return;
+    }
+    const step = TOUR_STEPS[currentStep];
+    function measure() {
+      if (!step || !step.target) {
+        setTargetRect(null);
+        return;
+      }
+      const el = document.querySelector(step.target);
+      if (!el) {
+        setTargetRect(null);
+        return;
+      }
+      const r = el.getBoundingClientRect();
+      setTargetRect({ top: r.top, left: r.left, right: r.right, bottom: r.bottom, width: r.width, height: r.height });
+    }
+    measure();
+    let timer = null;
+    const onResize = () => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(measure, 100);
+    };
+    window.addEventListener('resize', onResize);
+    window.addEventListener('scroll', onResize, true);
+    return () => {
+      window.removeEventListener('resize', onResize);
+      window.removeEventListener('scroll', onResize, true);
+      if (timer) clearTimeout(timer);
+    };
+  }, [currentStep]);
+
+  const completeTour = useCallback(() => {
+    try { localStorage.setItem('beastmode-tour-completed', 'true'); } catch (_) {}
+    setCurrentStep(null);
+  }, []);
+
+  // Escape to skip.
+  useEffect(() => {
+    if (currentStep === null) return;
+    const onKey = (e) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        completeTour();
+      }
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [currentStep, completeTour]);
+
+  if (currentStep === null) return null;
+
+  const step = TOUR_STEPS[currentStep];
+  const isLast = currentStep === TOUR_STEPS.length - 1;
+  const padding = 8;
+
+  // Spotlight position
+  const spotlightStyle = targetRect ? {
+    top: (targetRect.top - padding) + 'px',
+    left: (targetRect.left - padding) + 'px',
+    width: (targetRect.width + padding * 2) + 'px',
+    height: (targetRect.height + padding * 2) + 'px',
+  } : null;
+
+  // Tooltip position
+  const tooltipWidth = 380;
+  const tooltipApproxHeight = 220;
+  const margin = 16;
+  let tooltipStyle = {};
+  if (!targetRect || step.placement === 'center') {
+    tooltipStyle = {
+      top: '50%',
+      left: '50%',
+      transform: 'translate(-50%, -50%)',
+    };
+  } else if (step.placement === 'right') {
+    let top = targetRect.top + targetRect.height / 2 - tooltipApproxHeight / 2;
+    let left = targetRect.right + margin;
+    top = Math.max(margin, Math.min(top, window.innerHeight - tooltipApproxHeight - margin));
+    left = Math.max(margin, Math.min(left, window.innerWidth - tooltipWidth - margin));
+    tooltipStyle = { top: top + 'px', left: left + 'px' };
+  } else if (step.placement === 'bottom') {
+    let top = targetRect.bottom + margin;
+    let left = targetRect.left + targetRect.width / 2 - tooltipWidth / 2;
+    top = Math.max(margin, Math.min(top, window.innerHeight - tooltipApproxHeight - margin));
+    left = Math.max(margin, Math.min(left, window.innerWidth - tooltipWidth - margin));
+    tooltipStyle = { top: top + 'px', left: left + 'px' };
+  } else if (step.placement === 'bottom-start') {
+    let top = targetRect.bottom + margin;
+    let left = targetRect.left;
+    top = Math.max(margin, Math.min(top, window.innerHeight - tooltipApproxHeight - margin));
+    left = Math.max(margin, Math.min(left, window.innerWidth - tooltipWidth - margin));
+    tooltipStyle = { top: top + 'px', left: left + 'px' };
+  } else {
+    tooltipStyle = { top: '50%', left: '50%', transform: 'translate(-50%, -50%)' };
+  }
+
+  const styleStr = (obj) => Object.entries(obj).map(([k, v]) => {
+    const kebab = k.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+    return kebab + ':' + v;
+  }).join(';');
+
+  return html`
+    <div>
+      <div class="tour-backdrop" onClick=${completeTour}></div>
+      ${spotlightStyle ? html`<div class="tour-spotlight" style=${styleStr(spotlightStyle)}></div>` : null}
+      <div class="tour-tooltip" data-testid="tour-tooltip" style=${styleStr(tooltipStyle)} onClick=${(e) => e.stopPropagation()}>
+        <div class="tour-step-indicator">
+          ${TOUR_STEPS.map((_, i) => html`
+            <span key=${i} class=${'tour-step-dot' + (i === currentStep ? ' active' : '')}></span>
+          `)}
+        </div>
+        <h3>${step.title}</h3>
+        <p>${step.body}</p>
+        <div class="tour-actions">
+          <button class="tour-skip" data-testid="tour-skip" onClick=${completeTour}>Skip Tour</button>
+          <div class="tour-actions-right">
+            ${currentStep > 0 && html`
+              <button class="btn" data-testid="tour-back" onClick=${() => setCurrentStep(s => s - 1)}>Back</button>
+            `}
+            <button class="btn btn-primary" data-testid="tour-next" onClick=${() => {
+              if (isLast) {
+                completeTour();
+              } else {
+                setCurrentStep(s => s + 1);
+              }
+            }}>${isLast ? 'Get Started' : 'Next'}</button>
+          </div>
+        </div>
+      </div>
+    </div>
+  `;
+}
+
 function App() {
   const hash = useHash();
   const { theme, toggle: toggleTheme } = useTheme();
@@ -10787,6 +11381,7 @@ function App() {
         <${FactoryStatusBar} />
         ${page}
       </main>
+      <${OnboardingTour} />
     </div>
   `;
 }

package/dist/web/build-commit.txt

@@ -1 +1 @@
-bb5cfbcb14116ecf6845a1f8dd4282def11ac1a5
+f21d1ff83dc59d5ca4ea41a6e71c4ede76ee5ac7

package/dist/web/build-stamp.txt

@@ -1 +1 @@
-20260509-151332-bb5cfbc
+20260509-231045-f21d1ff

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beastmode-develeap/beastmode",
-  "version": "0.1.213",
+  "version": "0.1.215",
   "description": "BeastMode Dark Factory — turn intent into verified software",
   "type": "module",
   "bin": {