Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat: add guided operator walkthroughs

Juan Denisd6950cc40f4a
diff --git a/backend/app/api/walkthroughs.py b/backend/app/api/walkthroughs.py
new file mode 100644
index 00000000..43686c30
--- /dev/null
+++ b/backend/app/api/walkthroughs.py
@@ -0,0 +1,31 @@
+"""Self-scoped guided walkthrough progress API."""
+
+from flask import Blueprint, jsonify, request
+
+from app.middleware.rbac import get_current_user, require_role, viewer_required
+from app.services.walkthrough_service import (
+ WalkthroughService,
+ WalkthroughStateError,
+)
+
+
+walkthroughs_bp = Blueprint('walkthroughs', __name__)
+
+
+@walkthroughs_bp.route('/state', methods=['GET'])
+@viewer_required
+def get_walkthrough_state():
+ user = get_current_user()
+ return jsonify({'state': WalkthroughService.get_state(user.id)}), 200
+
+
+@walkthroughs_bp.route('/state', methods=['PUT'])
+@require_role('admin', 'developer', 'viewer')
+def update_walkthrough_state():
+ user = get_current_user()
+ data = request.get_json(silent=True) or {}
+ try:
+ state = WalkthroughService.save_state(user.id, data.get('state', data))
+ except WalkthroughStateError as exc:
+ return jsonify({'error': str(exc)}), 400
+ return jsonify({'success': True, 'state': state}), 200
diff --git a/backend/app/core_blueprints.py b/backend/app/core_blueprints.py
index 1b0503c1..815b2799 100644
--- a/backend/app/core_blueprints.py
+++ b/backend/app/core_blueprints.py
@@ -88,6 +88,11 @@ CORE_BLUEPRINTS: tuple[BlueprintSpec, ...] = (
BlueprintSpec('app.api.snapshots', 'snapshots_bp', '/api/v1/apps'),
BlueprintSpec('app.api.manifests', 'manifests_bp', '/api/v1/manifests'),
BlueprintSpec('app.api.recipes', 'recipes_bp', '/api/v1/recipes'),
+ BlueprintSpec(
+ 'app.api.walkthroughs',
+ 'walkthroughs_bp',
+ '/api/v1/walkthroughs',
+ ),
BlueprintSpec('app.api.projects', 'projects_bp', '/api/v1/projects'),
BlueprintSpec('app.api.environments', 'environments_bp', '/api/v1/environments'),
BlueprintSpec(
diff --git a/backend/app/services/walkthrough_service.py b/backend/app/services/walkthrough_service.py
new file mode 100644
index 00000000..908f0e66
--- /dev/null
+++ b/backend/app/services/walkthrough_service.py
@@ -0,0 +1,127 @@
+"""Per-user progress storage for guided UI walkthroughs.
+
+Walkthrough definitions live in the frontend so they can point at real routes
+and controls without turning the backend into a second navigation registry.
+Only the small, non-sensitive progress ledger is persisted here. The existing
+``system_settings`` JSON store keeps this additive and migration-free while a
+user-id-qualified key preserves strict self-scoping.
+"""
+
+import re
+from typing import Any, Dict
+
+from app import db
+from app.models.system_settings import SystemSettings
+
+
+WALKTHROUGH_STATE_VERSION = 1
+_KEY_PREFIX = 'walkthroughs.user.'
+_ID_RE = re.compile(r'^[a-z0-9][a-z0-9._-]{0,79}$')
+_STATUSES = {'active', 'completed', 'dismissed'}
+
+
+class WalkthroughStateError(ValueError):
+ """Raised when a client submits an invalid progress ledger."""
+
+
+class WalkthroughService:
+
+ @staticmethod
+ def _key(user_id: int) -> str:
+ return f'{_KEY_PREFIX}{int(user_id)}'
+
+ @classmethod
+ def get_state(cls, user_id: int) -> Dict[str, Any]:
+ raw = SystemSettings.get(cls._key(user_id), {})
+ if not isinstance(raw, dict):
+ return cls.empty_state()
+ try:
+ return cls.normalize_state(raw)
+ except WalkthroughStateError:
+ return cls.empty_state()
+
+ @classmethod
+ def save_state(cls, user_id: int, raw: Any) -> Dict[str, Any]:
+ state = cls.normalize_state(raw)
+ SystemSettings.set(
+ key=cls._key(user_id),
+ value=state,
+ value_type='json',
+ description='Per-user guided walkthrough progress',
+ user_id=user_id,
+ )
+ db.session.commit()
+ return state
+
+ @staticmethod
+ def empty_state() -> Dict[str, Any]:
+ return {'version': WALKTHROUGH_STATE_VERSION, 'active_id': None, 'progress': {}}
+
+ @classmethod
+ def normalize_state(cls, raw: Any) -> Dict[str, Any]:
+ if not isinstance(raw, dict):
+ raise WalkthroughStateError('state must be an object')
+
+ active_id = raw.get('active_id')
+ if active_id is not None and not cls._valid_id(active_id):
+ raise WalkthroughStateError('active_id is invalid')
+
+ progress = raw.get('progress', {})
+ if not isinstance(progress, dict):
+ raise WalkthroughStateError('progress must be an object')
+ if len(progress) > 64:
+ raise WalkthroughStateError('too many walkthrough progress entries')
+
+ normalized = {}
+ for walkthrough_id, entry in progress.items():
+ if not cls._valid_id(walkthrough_id):
+ raise WalkthroughStateError('walkthrough id is invalid')
+ if not isinstance(entry, dict):
+ raise WalkthroughStateError(f'{walkthrough_id} progress must be an object')
+
+ status = entry.get('status', 'active')
+ if status not in _STATUSES:
+ raise WalkthroughStateError(f'{walkthrough_id} status is invalid')
+ completed_steps = entry.get('completed_steps', [])
+ if not isinstance(completed_steps, list) or len(completed_steps) > 64:
+ raise WalkthroughStateError(
+ f'{walkthrough_id} completed_steps must be a bounded array')
+
+ clean_steps = []
+ for step_id in completed_steps:
+ if not cls._valid_id(step_id):
+ raise WalkthroughStateError(
+ f'{walkthrough_id} contains an invalid step id')
+ if step_id not in clean_steps:
+ clean_steps.append(step_id)
+
+ normalized[walkthrough_id] = {
+ 'status': status,
+ 'completed_steps': clean_steps,
+ 'started_at': cls._timestamp(entry.get('started_at')),
+ 'updated_at': cls._timestamp(entry.get('updated_at')),
+ 'completed_at': cls._timestamp(entry.get('completed_at')),
+ }
+
+ if active_id and active_id not in normalized:
+ raise WalkthroughStateError('active_id has no matching progress entry')
+ if active_id and normalized[active_id]['status'] != 'active':
+ active_id = None
+
+ return {
+ 'version': WALKTHROUGH_STATE_VERSION,
+ 'active_id': active_id,
+ 'progress': normalized,
+ }
+
+ @staticmethod
+ def _valid_id(value: Any) -> bool:
+ return isinstance(value, str) and bool(_ID_RE.fullmatch(value))
+
+ @staticmethod
+ def _timestamp(value: Any):
+ if value is None:
+ return None
+ if not isinstance(value, str) or len(value) > 40:
+ raise WalkthroughStateError('timestamps must be ISO strings')
+ return value
diff --git a/backend/tests/test_core_blueprint_registry.py b/backend/tests/test_core_blueprint_registry.py
index fdfc7c97..3d37a3b5 100644
--- a/backend/tests/test_core_blueprint_registry.py
+++ b/backend/tests/test_core_blueprint_registry.py
@@ -7,9 +7,9 @@ from pathlib import Path
from app.core_blueprints import CORE_BLUEPRINTS
-EXPECTED_CORE_BLUEPRINT_COUNT = 110
+EXPECTED_CORE_BLUEPRINT_COUNT = 111
EXPECTED_MANIFEST_SHA256 = (
- '8d70318fa935817c1b92b03f186c75c8c9cd6eb7aa3483e0bc44b735fd5c5722'
+ '560d72b4a31a6ad7ac8f1c9dd906000c7fd3c315f9aaf7e2df61fa98fb782d6e'
)
diff --git a/backend/tests/test_route_authz_sweep.py b/backend/tests/test_route_authz_sweep.py
index a17c7949..b4c4ad53 100644
--- a/backend/tests/test_route_authz_sweep.py
+++ b/backend/tests/test_route_authz_sweep.py
@@ -206,6 +206,7 @@ VIEWER_WRITABLE = {
'notifications.test_user_notification',
'notifications.unmute_own_email',
'two_factor.initiate_2fa_setup',
+ 'walkthroughs.update_walkthrough_state',
'mobile.execute_quick_action',
# STATELESS — parse/validate/dry-run helpers; no persisted mutation.
'cron.preview_schedule',
diff --git a/backend/tests/test_walkthroughs.py b/backend/tests/test_walkthroughs.py
new file mode 100644
index 00000000..b617b730
--- /dev/null
+++ b/backend/tests/test_walkthroughs.py
@@ -0,0 +1,55 @@
+"""Guided walkthrough progress is validated and strictly self-scoped."""
+
+from factories import headers_for, make_user
+
+
+def _state(step='open-wizard'):
+ return {
+ 'version': 1,
+ 'active_id': 'create-service',
+ 'progress': {
+ 'create-service': {
+ 'status': 'active',
+ 'completed_steps': [step],
+ 'started_at': '2026-08-21T12:00:00.000Z',
+ 'updated_at': '2026-08-21T12:01:00.000Z',
+ 'completed_at': None,
+ },
+ },
+ }
+
+
+def test_walkthrough_state_round_trip_is_self_scoped(client, db_session):
+ first = make_user(db_session, role='viewer', username='guide-one')
+ second = make_user(db_session, role='viewer', username='guide-two')
+
+ response = client.put(
+ '/api/v1/walkthroughs/state', headers=headers_for(first),
+ json={'state': _state()})
+ assert response.status_code == 200
+ assert response.get_json()['state']['active_id'] == 'create-service'
+
+ response = client.get(
+ '/api/v1/walkthroughs/state', headers=headers_for(second))
+ assert response.status_code == 200
+ assert response.get_json()['state']['progress'] == {}
+
+ response = client.get(
+ '/api/v1/walkthroughs/state', headers=headers_for(first))
+ assert response.get_json()['state']['progress']['create-service'][
+ 'completed_steps'] == ['open-wizard']
+
+
+def test_walkthrough_state_rejects_unbounded_or_unknown_data(client, db_session):
+ user = make_user(db_session, role='viewer', username='guide-invalid')
+ bad = _state()
+ bad['progress']['create-service']['status'] = 'invented'
+ response = client.put(
+ '/api/v1/walkthroughs/state', headers=headers_for(user),
+ json={'state': bad})
+ assert response.status_code == 400
+
+
+def test_walkthrough_state_requires_authentication(client):
+ assert client.get('/api/v1/walkthroughs/state').status_code in (401, 422)
+ assert client.put('/api/v1/walkthroughs/state', json={}).status_code in (401, 422)
diff --git a/frontend/src/components/WalkthroughHub.jsx b/frontend/src/components/WalkthroughHub.jsx
new file mode 100644
index 00000000..d85afecd
--- /dev/null
+++ b/frontend/src/components/WalkthroughHub.jsx
@@ -0,0 +1,249 @@
+import {
+ ArrowRight,
+ BookOpenCheck,
+ Boxes,
+ Check,
+ ChevronLeft,
+ Circle,
+ Clock3,
+ ListChecks,
+ RotateCcw,
+ ShieldCheck,
+ X,
+} from 'lucide-react';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { Button } from '@/components/ui/button';
+import { useWalkthroughs } from '../contexts/walkthroughContextValue';
+import { getWalkthroughProgress } from '../services/walkthroughState';
+import Pill from './ds/Pill';
+import IconButton from './IconButton';
+
+
+const ICONS = { service: Boxes, security: ShieldCheck };
+
+function WalkthroughCard({ walkthrough, state, onStart, t }) {
+ const Icon = ICONS[walkthrough.icon] || BookOpenCheck;
+ const progress = getWalkthroughProgress(state, walkthrough);
+ const status = progress.entry?.status;
+ const completed = status === 'completed';
+ const active = status === 'active';
+
+ return (
+ <article className={`walkthrough-card walkthrough-card--${walkthrough.tone}`}>
+ <div className="walkthrough-card__icon"><Icon size={18} /></div>
+ <div className="walkthrough-card__body">
+ <div className="walkthrough-card__meta">
+ <span><Clock3 size={12} /> {walkthrough.duration}</span>
+ {completed && <Pill kind="green">{t('app.walkthroughs.completed', 'Completed')}</Pill>}
+ {active && <Pill kind="cyan">{progress.count}/{progress.total}</Pill>}
+ </div>
+ <h3>{walkthrough.title}</h3>
+ <p>{walkthrough.description}</p>
+ <Button
+ type="button"
+ variant={active ? 'default' : 'outline'}
+ size="sm"
+ onClick={() => onStart(walkthrough.id)}
+ >
+ {completed ? <RotateCcw size={14} /> : <ArrowRight size={14} />}
+ {completed
+ ? t('app.walkthroughs.runAgain', 'Run again')
+ : active
+ ? t('app.walkthroughs.resume', 'Resume')
+ : t('app.walkthroughs.start', 'Start walkthrough')}
+ </Button>
+ </div>
+ </article>
+ );
+}
+
+function ActiveWalkthrough({ walkthrough, progress, currentStep, onBrowse, t }) {
+ const {
+ checkCurrent,
+ dismiss,
+ goToCurrent,
+ } = useWalkthroughs();
+ const Icon = ICONS[walkthrough.icon] || BookOpenCheck;
+ const [checking, setChecking] = useState(false);
+
+ const performAction = async () => {
+ if (!currentStep?.check) {
+ goToCurrent();
+ return;
+ }
+ setChecking(true);
+ try { await checkCurrent(); } finally { setChecking(false); }
+ };
+
+ return (
+ <>
+ <header className="walkthrough-hub__active-head">
+ <Button type="button" variant="ghost" size="sm" onClick={onBrowse}>
+ <ChevronLeft size={14} /> {t('app.walkthroughs.allGuides', 'All guides')}
+ </Button>
+ <div className={`walkthrough-hub__active-icon is-${walkthrough.tone}`}><Icon size={19} /></div>
+ <span className="walkthrough-hub__eyebrow">
+ {t('app.walkthroughs.guidedOutcome', 'Guided outcome')}
+ </span>
+ <h2>{walkthrough.title}</h2>
+ <div className="walkthrough-hub__progress-copy">
+ <span>{t('app.walkthroughs.stepCount', 'Step {{current}} of {{total}}', {
+ current: Math.min(progress.count + 1, progress.total),
+ total: progress.total,
+ })}</span>
+ <strong>{progress.percent}%</strong>
+ </div>
+ <progress max="100" value={progress.percent} aria-label={t('app.walkthroughs.progress', 'Walkthrough progress')} />
+ </header>
+
+ <ol className="walkthrough-hub__steps">
+ {walkthrough.steps.map((step, index) => {
+ const done = progress.completed.includes(step.id);
+ const current = currentStep?.id === step.id;
+ return (
+ <li
+ key={step.id}
+ className={`${done ? 'is-done' : ''}${current ? ' is-current' : ''}`}
+ aria-current={current ? 'step' : undefined}
+ >
+ <span className="walkthrough-hub__step-marker">
+ {done ? <Check size={13} /> : current ? <Circle size={11} /> : index + 1}
+ </span>
+ <div>
+ <strong>{step.title}</strong>
+ {(current || done) && <p>{step.description}</p>}
+ </div>
+ </li>
+ );
+ })}
+ </ol>
+
+ {currentStep && (
+ <div className="walkthrough-hub__next">
+ <span>{t('app.walkthroughs.now', 'Now')}</span>
+ <strong>{currentStep.title}</strong>
+ <p>{currentStep.description}</p>
+ <Button type="button" onClick={performAction} disabled={checking}>
+ {checking
+ ? t('app.walkthroughs.checking', 'Checking…')
+ : currentStep.action}
+ {!checking && <ArrowRight size={15} />}
+ </Button>
+ </div>
+ )}
+
+ <footer className="walkthrough-hub__footer">
+ <span>{t('app.walkthroughs.progressSaved', 'Progress is saved to your account.')}</span>
+ <Button type="button" variant="ghost" size="sm" onClick={() => dismiss(walkthrough.id)}>
+ {t('app.walkthroughs.stop', 'Stop walkthrough')}
+ </Button>
+ </footer>
+ </>
+ );
+}
+
+export default function WalkthroughHub() {
+ const { t } = useTranslation();
+ const {
+ state,
+ open,
+ setOpen,
+ walkthroughs,
+ activeWalkthrough,
+ activeProgress,
+ currentStep,
+ start,
+ } = useWalkthroughs();
+ const [browse, setBrowse] = useState(false);
+
+ const showActive = activeWalkthrough && !browse;
+ const completedCount = walkthroughs.filter(
+ (walkthrough) => state.progress?.[walkthrough.id]?.status === 'completed',
+ ).length;
+
+ const launch = () => {
+ setBrowse(!activeWalkthrough);
+ setOpen(!open);
+ };
+
+ const selectWalkthrough = (id) => {
+ start(id);
+ setBrowse(false);
+ };
+
+ return (
+ <div className={`walkthrough-shell${open ? ' is-open' : ''}`}>
+ <Button
+ type="button"
+ className="walkthrough-shell__launcher"
+ variant="outline"
+ onClick={launch}
+ aria-expanded={open}
+ aria-controls="walkthrough-hub"
+ >
+ <BookOpenCheck size={16} />
+ <span>{activeWalkthrough
+ ? t('app.walkthroughs.activeGuide', 'Guide · {{count}}/{{total}}', {
+ count: activeProgress.count,
+ total: activeProgress.total,
+ })
+ : t('app.walkthroughs.guides', 'Guides')}</span>
+ </Button>
+
+ {open && (
+ <aside id="walkthrough-hub" className="walkthrough-hub" aria-label={t('app.walkthroughs.guides', 'Guides')}>
+ <div className="walkthrough-hub__topline">
+ <span><ListChecks size={14} /> {t('app.walkthroughs.operatorGuides', 'Operator guides')}</span>
+ <IconButton
+ icon={<X size={15} />}
+ label={t('common.actions.close', 'Close')}
+ onClick={() => setOpen(false)}
+ />
+ </div>
+
+ {showActive ? (
+ <ActiveWalkthrough
+ walkthrough={activeWalkthrough}
+ progress={activeProgress}
+ currentStep={currentStep}
+ onBrowse={() => setBrowse(true)}
+ t={t}
+ />
+ ) : (
+ <div className="walkthrough-hub__library">
+ <header>
+ <span className="walkthrough-hub__eyebrow">
+ {t('app.walkthroughs.learnByDoing', 'Learn by doing')}
+ </span>
+ <h2>{t('app.walkthroughs.makeTheNextMove', 'Make the next move')}</h2>
+ <p>{t(
+ 'app.walkthroughs.libraryDescription',
+ 'Walkthroughs guide the controls. Recipes automate the server work underneath.',
+ )}</p>
+ <span className="walkthrough-hub__library-count">
+ {t('app.walkthroughs.completedCount', '{{count}} of {{total}} completed', {
+ count: completedCount,
+ total: walkthroughs.length,
+ })}
+ </span>
+ </header>
+ <div className="walkthrough-hub__cards">
+ {walkthroughs.map((walkthrough) => (
+ <WalkthroughCard
+ key={walkthrough.id}
+ walkthrough={walkthrough}
+ state={state}
+ onStart={selectWalkthrough}
+ t={t}
+ />
+ ))}
+ </div>
+ </div>
+ )}
+ </aside>
+ )}
+ </div>
+ );
+}
diff --git a/frontend/src/components/settings/SecuritySettingsTab.jsx b/frontend/src/components/settings/SecuritySettingsTab.jsx
index 8900e618..6be1556c 100644
--- a/frontend/src/components/settings/SecuritySettingsTab.jsx
+++ b/frontend/src/components/settings/SecuritySettingsTab.jsx
@@ -193,6 +193,9 @@ const SecuritySettingsTab = () => {
const data = await api.initiate2FASetup();
setSetupData(data);
setShowSetupModal(true);
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'two-factor-setup-started' },
+ }));
} catch (err) {
setTwoFAError(err.message);
} finally {
@@ -215,6 +218,9 @@ const SecuritySettingsTab = () => {
setShowBackupCodesModal(true);
setVerificationCode('');
load2FAStatus();
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'two-factor-enabled' },
+ }));
} catch (err) {
setTwoFAError(err.message || 'Invalid verification code');
} finally {
@@ -295,7 +301,7 @@ Keep these codes in a safe place.`;
)}
{/* Two-Factor Authentication Section */}
- <div {...register('security-2fa', 'settings-card two-fa-card')}>
+ <div {...register('security-2fa', 'settings-card two-fa-card')} data-walkthrough="two-factor-card">
<div className="two-fa-header">
<div className="two-fa-icon">
<svg viewBox="0 0 24 24" width="24" height="24" stroke="currentColor" fill="none" strokeWidth="2">
@@ -435,7 +441,7 @@ Keep these codes in a safe place.`;
{/* 2FA Setup Modal */}
{showSetupModal && setupData && (
<Modal open={true} onClose={() => setShowSetupModal(false)} title={t('app.securitySettingsTab.setUpTwoFactorAuthentication', 'Set Up Two-Factor Authentication')} size="md">
- <div className="setup-steps">
+ <div className="setup-steps" data-walkthrough="two-factor-verify">
<div className="setup-step">
<span className="step-number">1</span>
<div className="step-content">
diff --git a/frontend/src/contexts/WalkthroughContext.jsx b/frontend/src/contexts/WalkthroughContext.jsx
new file mode 100644
index 00000000..cf2394f9
--- /dev/null
+++ b/frontend/src/contexts/WalkthroughContext.jsx
@@ -0,0 +1,213 @@
+import {
+ useCallback,
+ useEffect,
+ useMemo,
+ useState,
+} from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+
+import {
+ WALKTHROUGHS,
+ WALKTHROUGH_BY_ID,
+ localizeWalkthroughs,
+} from '../data/walkthroughs';
+import api from '../services/api';
+import {
+ EMPTY_WALKTHROUGH_STATE,
+ completeWalkthroughStepState,
+ dismissWalkthroughState,
+ getWalkthroughProgress,
+ normalizeWalkthroughState,
+ routeMatches,
+ startWalkthroughState,
+} from '../services/walkthroughState';
+import { useAuth } from './AuthContext';
+import usePolling from '../hooks/usePolling';
+import { WalkthroughContext } from './walkthroughContextValue';
+
+
+const WALKTHROUGH_IDS = WALKTHROUGHS.map((item) => item.id);
+
+function storageKey(userId) {
+ return `serverkit.walkthroughs.v1.${userId || 'anonymous'}`;
+}
+
+function readCachedState(userId) {
+ try {
+ return normalizeWalkthroughState(
+ JSON.parse(localStorage.getItem(storageKey(userId)) || 'null'),
+ WALKTHROUGH_IDS,
+ );
+ } catch {
+ return { ...EMPTY_WALKTHROUGH_STATE };
+ }
+}
+
+export function WalkthroughProvider({ children }) {
+ const { t } = useTranslation();
+ const { user, hasPermission } = useAuth();
+ const location = useLocation();
+ const navigate = useNavigate();
+ const [state, setState] = useState(() => readCachedState(user?.id));
+ const [hydrated, setHydrated] = useState(false);
+ const [open, setOpen] = useState(false);
+
+ const localizedWalkthroughs = useMemo(() => localizeWalkthroughs(t), [t]);
+ const availableWalkthroughs = useMemo(() => localizedWalkthroughs.filter((item) => (
+ !item.permission || hasPermission(item.permission.feature, item.permission.level)
+ )), [hasPermission, localizedWalkthroughs]);
+
+ const activeWalkthrough = localizedWalkthroughs.find(
+ (walkthrough) => walkthrough.id === state.active_id,
+ ) || null;
+ const activeProgress = activeWalkthrough
+ ? getWalkthroughProgress(state, activeWalkthrough)
+ : null;
+ const currentStep = activeProgress?.currentStep || null;
+
+ useEffect(() => {
+ if (!user?.id) return undefined;
+ let cancelled = false;
+ setState(readCachedState(user.id));
+ setHydrated(false);
+ api.getWalkthroughState()
+ .then((response) => {
+ if (!cancelled) {
+ setState(normalizeWalkthroughState(response.state, WALKTHROUGH_IDS));
+ }
+ })
+ .catch(() => { /* local cache remains the offline fallback */ })
+ .finally(() => { if (!cancelled) setHydrated(true); });
+ return () => { cancelled = true; };
+ }, [user?.id]);
+
+ useEffect(() => {
+ if (!hydrated || !user?.id) return undefined;
+ try { localStorage.setItem(storageKey(user.id), JSON.stringify(state)); } catch { /* ignore */ }
+ const timer = setTimeout(() => {
+ api.updateWalkthroughState(state).catch(() => { /* local progress is retained */ });
+ }, 250);
+ return () => clearTimeout(timer);
+ }, [hydrated, state, user?.id]);
+
+ const start = useCallback((walkthroughId) => {
+ if (!WALKTHROUGH_BY_ID[walkthroughId]) return;
+ setState((previous) => startWalkthroughState(previous, walkthroughId));
+ setOpen(true);
+ }, []);
+
+ const completeStep = useCallback((walkthroughId, stepId) => {
+ const walkthrough = WALKTHROUGH_BY_ID[walkthroughId];
+ if (!walkthrough) return;
+ setState((previous) => completeWalkthroughStepState(
+ previous,
+ walkthroughId,
+ stepId,
+ walkthrough.steps.map((step) => step.id),
+ ));
+ }, []);
+
+ const dismiss = useCallback((walkthroughId) => {
+ setState((previous) => dismissWalkthroughState(previous, walkthroughId));
+ }, []);
+
+ useEffect(() => {
+ if (!activeWalkthrough || !currentStep?.route) return;
+ if (routeMatches(location.pathname, currentStep.route)) {
+ completeStep(activeWalkthrough.id, currentStep.id);
+ }
+ }, [activeWalkthrough, completeStep, currentStep, location.pathname]);
+
+ useEffect(() => {
+ const handleSignal = (event) => {
+ if (!activeWalkthrough) return;
+ if (event.detail?.type === 'two-factor-enabled'
+ && activeWalkthrough.id === 'enable-two-factor') {
+ activeWalkthrough.steps.forEach((step) => (
+ completeStep(activeWalkthrough.id, step.id)
+ ));
+ return;
+ }
+ if (!currentStep?.signal) return;
+ if (event.detail?.type === currentStep.signal) {
+ completeStep(activeWalkthrough.id, currentStep.id);
+ }
+ };
+ window.addEventListener('serverkit:walkthrough-signal', handleSignal);
+ return () => window.removeEventListener('serverkit:walkthrough-signal', handleSignal);
+ }, [activeWalkthrough, completeStep, currentStep]);
+
+ const checkCurrent = useCallback(async () => {
+ if (!activeWalkthrough) return false;
+ if (activeWalkthrough.id === 'enable-two-factor') {
+ const status = await api.get2FAStatus();
+ if (status?.enabled) {
+ activeWalkthrough.steps.forEach((step) => (
+ completeStep(activeWalkthrough.id, step.id)
+ ));
+ return true;
+ }
+ }
+ return false;
+ }, [activeWalkthrough, completeStep]);
+
+ usePolling(
+ () => checkCurrent(),
+ 5000,
+ { enabled: activeWalkthrough?.id === 'enable-two-factor' },
+ );
+
+ useEffect(() => {
+ if (!open || !currentStep?.target) return undefined;
+ let attempts = 0;
+ let target;
+ const findTarget = () => {
+ target = document.querySelector(currentStep.target);
+ if (target) {
+ target.classList.add('is-walkthrough-target');
+ return;
+ }
+ if (attempts++ < 20) timer = setTimeout(findTarget, 100);
+ };
+ let timer = setTimeout(findTarget, 50);
+ return () => {
+ clearTimeout(timer);
+ target?.classList.remove('is-walkthrough-target');
+ };
+ }, [currentStep?.target, location.pathname, open]);
+
+ const goToCurrent = useCallback(() => {
+ if (currentStep?.path) navigate(currentStep.path);
+ setOpen(true);
+ }, [currentStep, navigate]);
+
+ const value = useMemo(() => ({
+ state,
+ open,
+ setOpen,
+ walkthroughs: availableWalkthroughs,
+ activeWalkthrough,
+ activeProgress,
+ currentStep,
+ start,
+ dismiss,
+ completeStep,
+ checkCurrent,
+ goToCurrent,
+ }), [
+ activeProgress,
+ activeWalkthrough,
+ availableWalkthroughs,
+ checkCurrent,
+ completeStep,
+ currentStep,
+ dismiss,
+ goToCurrent,
+ open,
+ start,
+ state,
+ ]);
+
+ return <WalkthroughContext.Provider value={value}>{children}</WalkthroughContext.Provider>;
+}
diff --git a/frontend/src/contexts/walkthroughContextValue.js b/frontend/src/contexts/walkthroughContextValue.js
new file mode 100644
index 00000000..dce6d480
--- /dev/null
+++ b/frontend/src/contexts/walkthroughContextValue.js
@@ -0,0 +1,10 @@
+import { createContext, useContext } from 'react';
+
+
+export const WalkthroughContext = createContext(null);
+
+export function useWalkthroughs() {
+ const value = useContext(WalkthroughContext);
+ if (!value) throw new Error('useWalkthroughs must be used inside WalkthroughProvider');
+ return value;
+}
diff --git a/frontend/src/data/walkthroughs.js b/frontend/src/data/walkthroughs.js
new file mode 100644
index 00000000..0c99859c
--- /dev/null
+++ b/frontend/src/data/walkthroughs.js
@@ -0,0 +1,189 @@
+// Guided UI outcomes. Recipes automate server work; walkthroughs guide the
+// operator through product controls where intent or a human-held secret is
+// required. Stable ids are persisted, so never rename one without a migration.
+export const WALKTHROUGHS = Object.freeze([
+ {
+ id: 'create-service',
+ icon: 'service',
+ tone: 'cyan',
+ titleKey: 'app.walkthroughs.createServiceTitle',
+ title: 'Create your first service',
+ descriptionKey: 'app.walkthroughs.createServiceDescription',
+ description: 'Choose a source, review the detected runtime, and launch a service.',
+ durationKey: 'app.walkthroughs.fiveMinutes',
+ duration: 'About 5 minutes',
+ permission: { feature: 'applications', level: 'write' },
+ steps: [
+ {
+ id: 'open-wizard',
+ titleKey: 'app.walkthroughs.openServiceWizard',
+ title: 'Open the service wizard',
+ descriptionKey: 'app.walkthroughs.openServiceWizardDescription',
+ description: 'Start from ServerKit’s dedicated three-step service flow.',
+ path: '/services/new',
+ route: '/services/new',
+ target: '[data-walkthrough="new-service"]',
+ actionKey: 'app.walkthroughs.openWizard',
+ action: 'Open wizard',
+ },
+ {
+ id: 'choose-source',
+ titleKey: 'app.walkthroughs.chooseServiceSource',
+ title: 'Choose where the code lives',
+ descriptionKey: 'app.walkthroughs.chooseServiceSourceDescription',
+ description: 'Pick GitHub, another Git remote, a local path, or a ZIP upload.',
+ path: '/services/new',
+ signal: 'service-source-selected',
+ target: '[data-walkthrough="service-sources"]',
+ actionKey: 'app.walkthroughs.chooseSource',
+ action: 'Choose a source',
+ },
+ {
+ id: 'review-service',
+ titleKey: 'app.walkthroughs.reviewService',
+ title: 'Review the detected setup',
+ descriptionKey: 'app.walkthroughs.reviewServiceDescription',
+ description: 'Confirm the name, runtime, build method, project, and environment.',
+ path: '/services/new',
+ signal: 'service-review-ready',
+ target: '[data-walkthrough="service-review"]',
+ actionKey: 'app.walkthroughs.continueSetup',
+ action: 'Continue setup',
+ },
+ {
+ id: 'create-service',
+ titleKey: 'app.walkthroughs.launchService',
+ title: 'Create and launch the service',
+ descriptionKey: 'app.walkthroughs.launchServiceDescription',
+ description: 'Submit the reviewed configuration. The guide completes only after creation succeeds.',
+ path: '/services/new',
+ signal: 'service-created',
+ target: '[data-walkthrough="service-submit"]',
+ actionKey: 'app.walkthroughs.finishService',
+ action: 'Finish in the wizard',
+ },
+ ],
+ },
+ {
+ id: 'enable-two-factor',
+ icon: 'security',
+ tone: 'amber',
+ titleKey: 'app.walkthroughs.enableTwoFactorTitle',
+ title: 'Enable two-step authentication',
+ descriptionKey: 'app.walkthroughs.enableTwoFactorDescription',
+ description: 'Pair an authenticator, verify a code, and store your recovery codes.',
+ durationKey: 'app.walkthroughs.threeMinutes',
+ duration: 'About 3 minutes',
+ steps: [
+ {
+ id: 'open-security',
+ titleKey: 'app.walkthroughs.openSecuritySettings',
+ title: 'Open account security',
+ descriptionKey: 'app.walkthroughs.openSecuritySettingsDescription',
+ description: 'Go directly to your personal two-factor authentication card.',
+ path: '/settings/security?focus=setting:security-2fa',
+ route: '/settings/security',
+ target: '[data-walkthrough="two-factor-card"]',
+ actionKey: 'app.walkthroughs.openSecurity',
+ action: 'Open security',
+ },
+ {
+ id: 'pair-authenticator',
+ titleKey: 'app.walkthroughs.pairAuthenticator',
+ title: 'Pair your authenticator',
+ descriptionKey: 'app.walkthroughs.pairAuthenticatorDescription',
+ description: 'Scan the QR code, then enter the six-digit code from your app.',
+ path: '/settings/security?focus=setting:security-2fa',
+ signal: 'two-factor-setup-started',
+ target: '[data-walkthrough="two-factor-card"]',
+ actionKey: 'app.walkthroughs.startEnrollment',
+ action: 'Start enrollment',
+ },
+ {
+ id: 'verify-two-factor',
+ titleKey: 'app.walkthroughs.verifyAndSaveCodes',
+ title: 'Verify and save recovery codes',
+ descriptionKey: 'app.walkthroughs.verifyAndSaveCodesDescription',
+ description: 'The guide verifies the live account status—it never stores your code or secret.',
+ path: '/settings/security?focus=setting:security-2fa',
+ signal: 'two-factor-enabled',
+ check: 'two-factor-enabled',
+ target: '[data-walkthrough="two-factor-verify"]',
+ actionKey: 'app.walkthroughs.checkStatus',
+ action: 'Check status',
+ },
+ ],
+ },
+]);
+
+export const WALKTHROUGH_BY_ID = Object.freeze(Object.fromEntries(
+ WALKTHROUGHS.map((walkthrough) => [walkthrough.id, walkthrough]),
+));
+
+// Keep every translation key literal for the i18n extraction gate while the
+// execution registry above stays stable and locale-neutral.
+export function localizeWalkthroughs(t) {
+ const copy = {
+ 'create-service': {
+ title: t('app.walkthroughs.createServiceTitle', 'Create your first service'),
+ description: t('app.walkthroughs.createServiceDescription', 'Choose a source, review the detected runtime, and launch a service.'),
+ duration: t('app.walkthroughs.fiveMinutes', 'About 5 minutes'),
+ steps: [
+ {
+ title: t('app.walkthroughs.openServiceWizard', 'Open the service wizard'),
+ description: t('app.walkthroughs.openServiceWizardDescription', 'Start from ServerKit’s dedicated three-step service flow.'),
+ action: t('app.walkthroughs.openWizard', 'Open wizard'),
+ },
+ {
+ title: t('app.walkthroughs.chooseServiceSource', 'Choose where the code lives'),
+ description: t('app.walkthroughs.chooseServiceSourceDescription', 'Pick GitHub, another Git remote, a local path, or a ZIP upload.'),
+ action: t('app.walkthroughs.chooseSource', 'Choose a source'),
+ },
+ {
+ title: t('app.walkthroughs.reviewService', 'Review the detected setup'),
+ description: t('app.walkthroughs.reviewServiceDescription', 'Confirm the name, runtime, build method, project, and environment.'),
+ action: t('app.walkthroughs.continueSetup', 'Continue setup'),
+ },
+ {
+ title: t('app.walkthroughs.launchService', 'Create and launch the service'),
+ description: t('app.walkthroughs.launchServiceDescription', 'Submit the reviewed configuration. The guide completes only after creation succeeds.'),
+ action: t('app.walkthroughs.finishService', 'Finish in the wizard'),
+ },
+ ],
+ },
+ 'enable-two-factor': {
+ title: t('app.walkthroughs.enableTwoFactorTitle', 'Enable two-step authentication'),
+ description: t('app.walkthroughs.enableTwoFactorDescription', 'Pair an authenticator, verify a code, and store your recovery codes.'),
+ duration: t('app.walkthroughs.threeMinutes', 'About 3 minutes'),
+ steps: [
+ {
+ title: t('app.walkthroughs.openSecuritySettings', 'Open account security'),
+ description: t('app.walkthroughs.openSecuritySettingsDescription', 'Go directly to your personal two-factor authentication card.'),
+ action: t('app.walkthroughs.openSecurity', 'Open security'),
+ },
+ {
+ title: t('app.walkthroughs.pairAuthenticator', 'Pair your authenticator'),
+ description: t('app.walkthroughs.pairAuthenticatorDescription', 'Scan the QR code, then enter the six-digit code from your app.'),
+ action: t('app.walkthroughs.startEnrollment', 'Start enrollment'),
+ },
+ {
+ title: t('app.walkthroughs.verifyAndSaveCodes', 'Verify and save recovery codes'),
+ description: t('app.walkthroughs.verifyAndSaveCodesDescription', 'The guide verifies the live account status—it never stores your code or secret.'),
+ action: t('app.walkthroughs.checkStatus', 'Check status'),
+ },
+ ],
+ },
+ };
+
+ return WALKTHROUGHS.map((walkthrough) => {
+ const localized = copy[walkthrough.id];
+ return {
+ ...walkthrough,
+ ...localized,
+ steps: walkthrough.steps.map((step, index) => ({
+ ...step,
+ ...localized.steps[index],
+ })),
+ };
+ });
+}
diff --git a/frontend/src/i18n/locales/en.json b/frontend/src/i18n/locales/en.json
index b0e431d3..230c8be8 100644
--- a/frontend/src/i18n/locales/en.json
+++ b/frontend/src/i18n/locales/en.json
@@ -8126,6 +8126,54 @@
"warnings": "warnings ·",
"warnings2": "Warnings ("
},
+ "walkthroughs": {
+ "activeGuide": "Guide · {{count}}/{{total}}",
+ "allGuides": "All guides",
+ "checkStatus": "Check status",
+ "checking": "Checking…",
+ "chooseServiceSource": "Choose where the code lives",
+ "chooseServiceSourceDescription": "Pick GitHub, another Git remote, a local path, or a ZIP upload.",
+ "chooseSource": "Choose a source",
+ "completed": "Completed",
+ "completedCount": "{{count}} of {{total}} completed",
+ "continueSetup": "Continue setup",
+ "createServiceDescription": "Choose a source, review the detected runtime, and launch a service.",
+ "createServiceTitle": "Create your first service",
+ "enableTwoFactorDescription": "Pair an authenticator, verify a code, and store your recovery codes.",
+ "enableTwoFactorTitle": "Enable two-step authentication",
+ "finishService": "Finish in the wizard",
+ "fiveMinutes": "About 5 minutes",
+ "guidedOutcome": "Guided outcome",
+ "guides": "Guides",
+ "launchService": "Create and launch the service",
+ "launchServiceDescription": "Submit the reviewed configuration. The guide completes only after creation succeeds.",
+ "learnByDoing": "Learn by doing",
+ "libraryDescription": "Walkthroughs guide the controls. Recipes automate the server work underneath.",
+ "makeTheNextMove": "Make the next move",
+ "now": "Now",
+ "openSecurity": "Open security",
+ "openSecuritySettings": "Open account security",
+ "openSecuritySettingsDescription": "Go directly to your personal two-factor authentication card.",
+ "openServiceWizard": "Open the service wizard",
+ "openServiceWizardDescription": "Start from ServerKit’s dedicated three-step service flow.",
+ "openWizard": "Open wizard",
+ "operatorGuides": "Operator guides",
+ "pairAuthenticator": "Pair your authenticator",
+ "pairAuthenticatorDescription": "Scan the QR code, then enter the six-digit code from your app.",
+ "progress": "Walkthrough progress",
+ "progressSaved": "Progress is saved to your account.",
+ "resume": "Resume",
+ "reviewService": "Review the detected setup",
+ "reviewServiceDescription": "Confirm the name, runtime, build method, project, and environment.",
+ "runAgain": "Run again",
+ "start": "Start walkthrough",
+ "startEnrollment": "Start enrollment",
+ "stepCount": "Step {{current}} of {{total}}",
+ "stop": "Stop walkthrough",
+ "threeMinutes": "About 3 minutes",
+ "verifyAndSaveCodes": "Verify and save recovery codes",
+ "verifyAndSaveCodesDescription": "The guide verifies the live account status—it never stores your code or secret."
+ },
"webhookSubscriptionModal": {
"cancel": "Cancel",
"createWebhookSubscription": "Create Webhook Subscription",
diff --git a/frontend/src/layouts/DashboardLayout.jsx b/frontend/src/layouts/DashboardLayout.jsx
index d19789ac..7d8af245 100644
--- a/frontend/src/layouts/DashboardLayout.jsx
+++ b/frontend/src/layouts/DashboardLayout.jsx
@@ -19,6 +19,8 @@ import ErrorBoundary from '../components/ErrorBoundary';
import { useShortcut } from '../hooks/useShortcut';
import { useTranslation } from 'react-i18next';
import { OperationsProvider } from '../contexts/OperationsContext';
+import { WalkthroughProvider } from '../contexts/WalkthroughContext';
+import WalkthroughHub from '../components/WalkthroughHub';
// The Automations extension (tramo) contributes /automations/edit/:slug with
// layout:'full', so it's picked up dynamically via fullPagePaths below.
@@ -102,6 +104,7 @@ const DashboardLayout = () => {
<LogsDrawerProvider>
<AIProvider>
<ConfirmProvider>
+ <WalkthroughProvider>
<div className="dashboard-layout">
<StagingBanner />
<MobileTopBar navOpen={navOpen} onToggle={() => setNavOpen(prev => !prev)} />
@@ -125,9 +128,11 @@ const DashboardLayout = () => {
</main>
<CommandPalette open={paletteOpen} onClose={() => setPaletteOpen(false)} />
<OperationsDock />
+ <WalkthroughHub />
<AIAssistant />
<PluginLoader api={api} />
</div>
+ </WalkthroughProvider>
</ConfirmProvider>
</AIProvider>
</LogsDrawerProvider>
diff --git a/frontend/src/pages/new-service/NewService.jsx b/frontend/src/pages/new-service/NewService.jsx
index dcaf7a03..fcd258c1 100644
--- a/frontend/src/pages/new-service/NewService.jsx
+++ b/frontend/src/pages/new-service/NewService.jsx
@@ -1,3 +1,4 @@
+import { useEffect } from 'react';
import { Link } from 'react-router-dom';
import { Check, Link2, Rocket } from 'lucide-react';
import { Button } from '@/components/ui/button';
@@ -22,6 +23,14 @@ const NewService = () => {
const form = useNewServiceForm();
const { step, setStep, submitting, canSubmit, canProceedFromConnect, handleSubmit } = form;
+ useEffect(() => {
+ if (step === 3) {
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'service-review-ready' },
+ }));
+ }
+ }, [step]);
+
useTopbarActions(() =>
<>
<DocsLink to="deploySources" />
@@ -36,7 +45,7 @@ const NewService = () => {
);
return (
- <div className="sk-tabgroup__inner new-service-page">
+ <div className="sk-tabgroup__inner new-service-page" data-walkthrough="new-service">
{/* Slim stepper header */}
<nav className="new-service-page__stepper" aria-label={t('app.newService.progress', 'Progress')}>
{STEPS.map(({ n, label }) => {
@@ -86,7 +95,7 @@ const NewService = () => {
</Button>
)}
{step === 3 && (
- <Button type="submit" disabled={!canSubmit || submitting}>
+ <Button type="submit" data-walkthrough="service-submit" disabled={!canSubmit || submitting}>
<Rocket size={16} />
{submitting
? (form.sourceMode === 'local' ? 'Registering…' : form.sourceMode === 'upload' ? 'Uploading…' : 'Deploying…')
diff --git a/frontend/src/pages/new-service/ReviewStep.jsx b/frontend/src/pages/new-service/ReviewStep.jsx
index a45af9c0..8683b050 100644
--- a/frontend/src/pages/new-service/ReviewStep.jsx
+++ b/frontend/src/pages/new-service/ReviewStep.jsx
@@ -84,7 +84,7 @@ const ReviewStep = ({ form }) => {
};
return (
- <div className="new-service-page__step new-service-page__review">
+ <div className="new-service-page__step new-service-page__review" data-walkthrough="service-review">
<div className="new-service-page__step-head">
<h2>{t('app.reviewStep.reviewDeploy', 'Review & deploy')}</h2>
<p>{t('app.reviewStep.confirmTheDetectedSettingsThenCreate', 'Confirm the detected settings, then create the service.')}</p>
diff --git a/frontend/src/pages/new-service/SourceStep.jsx b/frontend/src/pages/new-service/SourceStep.jsx
index f67c1a7d..1bf0ac58 100644
--- a/frontend/src/pages/new-service/SourceStep.jsx
+++ b/frontend/src/pages/new-service/SourceStep.jsx
@@ -28,7 +28,7 @@ const SourceStep = ({ form }) => {
<h2>{t('app.sourceStep.howDoYouWantToDeploy', 'How do you want to deploy?')}</h2>
<p>{t('app.sourceStep.pickASourceYouCanChange', 'Pick a source. You can change it on the next step.')}</p>
</div>
- <div className="new-service-page__sources" role="radiogroup" aria-label={t('app.sourceStep.serviceSource', 'Service source')}>
+ <div className="new-service-page__sources" data-walkthrough="service-sources" role="radiogroup" aria-label={t('app.sourceStep.serviceSource', 'Service source')}>
{SOURCES.map(({ mode, Icon, title, sub }) => (
<button
key={mode}
diff --git a/frontend/src/pages/new-service/useNewServiceForm.js b/frontend/src/pages/new-service/useNewServiceForm.js
index c6b76188..c51b5928 100644
--- a/frontend/src/pages/new-service/useNewServiceForm.js
+++ b/frontend/src/pages/new-service/useNewServiceForm.js
@@ -323,6 +323,9 @@ export function useNewServiceForm() {
setSourceMode(mode);
if (mode === 'local') setAppType('docker');
if (mode === 'upload') setAppType('auto');
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'service-source-selected', mode },
+ }));
}
// Pick a template by id (deep link or list click): fetch its detail, then apply.
@@ -397,6 +400,9 @@ export function useNewServiceForm() {
...projectEnvPayload,
};
const result = await api.createManualApp(payload);
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'service-created', appId: result.app.id },
+ }));
toast.success(t('app.useNewServiceForm.manualServiceRegistered', 'Manual service registered'));
navigate(`/services/${result.app.id}`);
} else if (sourceMode === 'upload') {
@@ -409,6 +415,9 @@ export function useNewServiceForm() {
if (projectEnvPayload.project_id) formData.append('project_id', projectEnvPayload.project_id);
if (projectEnvPayload.environment_id) formData.append('environment_id', projectEnvPayload.environment_id);
const result = await api.uploadAppZip(formData);
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'service-created', appId: result.app.id },
+ }));
toast.success(t('app.useNewServiceForm.uploadServiceCreated', 'Upload service created'));
navigate(`/services/${result.app.id}`);
} else {
@@ -441,6 +450,9 @@ export function useNewServiceForm() {
}
const result = await api.createAppFromRepository(payload);
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'service-created', appId: result.app?.id },
+ }));
if (result.deploy_job_id) {
// A deploy job was queued — take the user straight to the
// full-page Deploy Console to watch the build/startup live.
diff --git a/frontend/src/services/__tests__/walkthroughState.test.mjs b/frontend/src/services/__tests__/walkthroughState.test.mjs
new file mode 100644
index 00000000..71937bb2
--- /dev/null
+++ b/frontend/src/services/__tests__/walkthroughState.test.mjs
@@ -0,0 +1,74 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+ completeWalkthroughStepState,
+ dismissWalkthroughState,
+ getWalkthroughProgress,
+ normalizeWalkthroughState,
+ routeMatches,
+ startWalkthroughState,
+} from '../walkthroughState.js';
+
+
+const walkthrough = {
+ id: 'create-service',
+ steps: [{ id: 'open' }, { id: 'choose' }, { id: 'launch' }],
+};
+
+test('starts, resumes, and completes one walkthrough without losing other progress', () => {
+ const initial = normalizeWalkthroughState({
+ active_id: null,
+ progress: {
+ old: { status: 'completed', completed_steps: ['done'] },
+ },
+ }, ['old', 'create-service']);
+ const started = startWalkthroughState(initial, walkthrough.id, 'start');
+ assert.equal(started.active_id, walkthrough.id);
+ assert.equal(started.progress.old.status, 'completed');
+
+ const first = completeWalkthroughStepState(
+ started, walkthrough.id, 'open', walkthrough.steps.map((step) => step.id), 'one');
+ assert.deepEqual(getWalkthroughProgress(first, walkthrough).completed, ['open']);
+
+ const done = ['choose', 'launch'].reduce((state, stepId) => (
+ completeWalkthroughStepState(
+ state, walkthrough.id, stepId,
+ walkthrough.steps.map((step) => step.id), stepId)
+ ), first);
+ assert.equal(done.active_id, null);
+ assert.equal(done.progress[walkthrough.id].status, 'completed');
+ assert.equal(getWalkthroughProgress(done, walkthrough).percent, 100);
+});
+
+test('dismisses only the active guide and a restart begins from zero', () => {
+ const started = startWalkthroughState(
+ { version: 1, active_id: null, progress: {} }, walkthrough.id, 'start');
+ const dismissed = dismissWalkthroughState(started, walkthrough.id, 'stop');
+ assert.equal(dismissed.active_id, null);
+ assert.equal(dismissed.progress[walkthrough.id].status, 'dismissed');
+ const restarted = startWalkthroughState(dismissed, walkthrough.id, 'again');
+ assert.deepEqual(restarted.progress[walkthrough.id].completed_steps, []);
+});
+
+test('switching guides preserves unfinished progress for later resume', () => {
+ let state = startWalkthroughState(
+ { version: 1, active_id: null, progress: {} }, walkthrough.id, 'start');
+ state = completeWalkthroughStepState(
+ state, walkthrough.id, 'open', walkthrough.steps.map((step) => step.id), 'one');
+ state = startWalkthroughState(state, 'enable-two-factor', 'second');
+ const resumed = startWalkthroughState(state, walkthrough.id, 'resume');
+ assert.deepEqual(resumed.progress[walkthrough.id].completed_steps, ['open']);
+});
+
+test('drops unknown definitions and matches only route boundaries', () => {
+ const normalized = normalizeWalkthroughState({
+ active_id: 'removed-guide',
+ progress: { 'removed-guide': { status: 'active', completed_steps: [] } },
+ }, ['create-service']);
+ assert.equal(normalized.active_id, null);
+ assert.deepEqual(normalized.progress, {});
+ assert.equal(routeMatches('/settings/security', '/settings/security'), true);
+ assert.equal(routeMatches('/settings/security/sessions', '/settings/security'), true);
+ assert.equal(routeMatches('/settings/security-old', '/settings/security'), false);
+});
diff --git a/frontend/src/services/api/index.js b/frontend/src/services/api/index.js
index c6e7b17d..12e4180d 100644
--- a/frontend/src/services/api/index.js
+++ b/frontend/src/services/api/index.js
@@ -51,6 +51,7 @@ import * as monitorMethods from './monitors.js';
import * as viewMethods from './views.js';
import * as recycleBinMethods from './recycleBin.js';
import * as errorLogMethods from './errorLogs.js';
+import * as walkthroughMethods from './walkthroughs.js';
class ApiService extends ApiClient {
constructor() {
@@ -109,6 +110,7 @@ class ApiService extends ApiClient {
viewMethods,
recycleBinMethods,
errorLogMethods,
+ walkthroughMethods,
];
for (const mod of modules) {
for (const [key, fn] of Object.entries(mod)) {
diff --git a/frontend/src/services/api/walkthroughs.js b/frontend/src/services/api/walkthroughs.js
new file mode 100644
index 00000000..5c5abffd
--- /dev/null
+++ b/frontend/src/services/api/walkthroughs.js
@@ -0,0 +1,10 @@
+export async function getWalkthroughState() {
+ return this.request('/walkthroughs/state');
+}
+
+export async function updateWalkthroughState(state) {
+ return this.request('/walkthroughs/state', {
+ method: 'PUT',
+ body: { state },
+ });
+}
diff --git a/frontend/src/services/walkthroughState.js b/frontend/src/services/walkthroughState.js
new file mode 100644
index 00000000..6fb40fe1
--- /dev/null
+++ b/frontend/src/services/walkthroughState.js
@@ -0,0 +1,117 @@
+export const EMPTY_WALKTHROUGH_STATE = Object.freeze({
+ version: 1,
+ active_id: null,
+ progress: {},
+});
+
+const isoNow = () => new Date().toISOString();
+
+export function normalizeWalkthroughState(raw, knownIds = []) {
+ const allowed = new Set(knownIds);
+ const source = raw && typeof raw === 'object' ? raw : EMPTY_WALKTHROUGH_STATE;
+ const progress = {};
+ for (const [id, entry] of Object.entries(source.progress || {})) {
+ if (!allowed.has(id) || !entry || typeof entry !== 'object') continue;
+ progress[id] = {
+ status: ['active', 'completed', 'dismissed'].includes(entry.status)
+ ? entry.status
+ : 'active',
+ completed_steps: [...new Set(
+ Array.isArray(entry.completed_steps) ? entry.completed_steps : [],
+ )],
+ started_at: entry.started_at || null,
+ updated_at: entry.updated_at || null,
+ completed_at: entry.completed_at || null,
+ };
+ }
+ const activeId = allowed.has(source.active_id)
+ && progress[source.active_id]?.status === 'active'
+ ? source.active_id
+ : null;
+ return { version: 1, active_id: activeId, progress };
+}
+
+export function startWalkthroughState(state, walkthroughId, now = isoNow()) {
+ const current = state.progress?.[walkthroughId];
+ if (state.active_id === walkthroughId && current?.status === 'active') return state;
+ if (current?.status === 'active') {
+ return { ...state, active_id: walkthroughId };
+ }
+ return {
+ version: 1,
+ active_id: walkthroughId,
+ progress: {
+ ...(state.progress || {}),
+ [walkthroughId]: {
+ status: 'active',
+ completed_steps: [],
+ started_at: now,
+ updated_at: now,
+ completed_at: null,
+ },
+ },
+ };
+}
+
+export function completeWalkthroughStepState(
+ state,
+ walkthroughId,
+ stepId,
+ allStepIds,
+ now = isoNow(),
+) {
+ const current = state.progress?.[walkthroughId];
+ if (!current || current.status !== 'active') return state;
+ const completed = [...new Set([...(current.completed_steps || []), stepId])];
+ const done = allStepIds.every((id) => completed.includes(id));
+ return {
+ ...state,
+ active_id: done && state.active_id === walkthroughId ? null : state.active_id,
+ progress: {
+ ...state.progress,
+ [walkthroughId]: {
+ ...current,
+ status: done ? 'completed' : 'active',
+ completed_steps: completed,
+ updated_at: now,
+ completed_at: done ? now : null,
+ },
+ },
+ };
+}
+
+export function dismissWalkthroughState(state, walkthroughId, now = isoNow()) {
+ const current = state.progress?.[walkthroughId];
+ if (!current) return { ...state, active_id: null };
+ return {
+ ...state,
+ active_id: state.active_id === walkthroughId ? null : state.active_id,
+ progress: {
+ ...state.progress,
+ [walkthroughId]: {
+ ...current,
+ status: 'dismissed',
+ updated_at: now,
+ },
+ },
+ };
+}
+
+export function getWalkthroughProgress(state, walkthrough) {
+ const entry = state.progress?.[walkthrough.id];
+ const completed = entry?.completed_steps || [];
+ const total = walkthrough.steps.length;
+ const count = walkthrough.steps.filter((step) => completed.includes(step.id)).length;
+ return {
+ entry,
+ completed,
+ total,
+ count,
+ percent: total ? Math.round((count / total) * 100) : 0,
+ currentStep: walkthrough.steps.find((step) => !completed.includes(step.id)) || null,
+ };
+}
+
+export function routeMatches(pathname, route) {
+ return Boolean(route) && (pathname === route || pathname.startsWith(`${route}/`));
+}
diff --git a/frontend/src/styles/components/_walkthroughs.scss b/frontend/src/styles/components/_walkthroughs.scss
new file mode 100644
index 00000000..5659b84d
--- /dev/null
+++ b/frontend/src/styles/components/_walkthroughs.scss
@@ -0,0 +1,372 @@
+// Guided outcomes — a compact operator field manual beside the page, not a
+// modal tour that blocks the controls it is trying to teach.
+.walkthrough-shell {
+ position: fixed;
+ inset-inline-start: calc(#{$sidebar-width} + 168px);
+ inset-block-end: $space-4;
+ z-index: 1060;
+ font-family: $font-main;
+
+ &.is-open { z-index: 1120; }
+
+ &__launcher {
+ min-height: 42px;
+ gap: $space-2;
+ border-color: var(--border-strong);
+ border-radius: 999px;
+ background: var(--surface);
+ color: var(--text);
+ box-shadow: $shadow-lg;
+
+ svg { color: var(--amber); }
+ }
+}
+
+.walkthrough-hub {
+ position: absolute;
+ inset-inline-start: 0;
+ inset-block-end: 0;
+ display: flex;
+ flex-direction: column;
+ width: min(390px, calc(100vw - #{$sidebar-width} - #{$space-8}));
+ max-height: min(760px, calc(100vh - #{$space-8}));
+ overflow: hidden;
+ border: 1px solid var(--border-strong);
+ border-radius: $radius-lg;
+ background:
+ linear-gradient(var(--border-soft) 1px, transparent 1px),
+ linear-gradient(90deg, var(--border-soft) 1px, transparent 1px),
+ var(--surface);
+ background-size: 24px 24px;
+ box-shadow: $shadow-lg;
+ animation: walkthrough-enter 180ms ease-out;
+
+ &__topline {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ min-height: 45px;
+ padding: $space-2 $space-3 $space-2 $space-4;
+ border-bottom: 1px solid var(--border-strong);
+ background: color-mix(in srgb, var(--surface) 94%, transparent);
+
+ > span {
+ display: inline-flex;
+ align-items: center;
+ gap: $space-2;
+ color: var(--text-faint);
+ font-family: var(--mono);
+ font-size: 10px;
+ font-weight: $font-weight-semibold;
+ letter-spacing: 0.11em;
+ text-transform: uppercase;
+ }
+ }
+
+ &__eyebrow {
+ color: var(--amber);
+ font-family: var(--mono);
+ font-size: 10px;
+ font-weight: $font-weight-semibold;
+ letter-spacing: 0.13em;
+ text-transform: uppercase;
+ }
+
+ &__library,
+ &__steps {
+ overflow-y: auto;
+ overscroll-behavior: contain;
+ }
+
+ &__library {
+ padding: $space-5;
+ background: color-mix(in srgb, var(--surface) 97%, transparent);
+
+ > header {
+ padding: $space-1 0 $space-5;
+ border-bottom: 1px solid var(--border-soft);
+ }
+
+ h2 {
+ margin: $space-2 0 $space-2;
+ color: var(--text);
+ font-size: 1.35rem;
+ letter-spacing: -0.025em;
+ }
+
+ p {
+ max-width: 34ch;
+ margin: 0;
+ color: var(--text-muted);
+ font-size: $font-size-sm;
+ line-height: 1.55;
+ }
+ }
+
+ &__library-count {
+ display: inline-block;
+ margin-top: $space-3;
+ color: var(--text-faint);
+ font-family: var(--mono);
+ font-size: 10px;
+ }
+
+ &__cards {
+ display: grid;
+ gap: $space-3;
+ padding-top: $space-4;
+ }
+
+ &__active-head {
+ position: relative;
+ padding: $space-3 $space-5 $space-5;
+ border-bottom: 1px solid var(--border-strong);
+ background: color-mix(in srgb, var(--surface) 96%, transparent);
+
+ > .btn { margin-inline-start: -$space-3; margin-bottom: $space-4; }
+
+ h2 {
+ max-width: 16ch;
+ margin: $space-2 0 $space-4;
+ color: var(--text);
+ font-size: 1.28rem;
+ line-height: 1.15;
+ letter-spacing: -0.025em;
+ }
+
+ progress {
+ display: block;
+ width: 100%;
+ height: 5px;
+ overflow: hidden;
+ border: 0;
+ border-radius: 999px;
+ background: var(--surface-3);
+ color: var(--amber);
+ appearance: none;
+
+ &::-webkit-progress-bar { background: var(--surface-3); }
+ &::-webkit-progress-value { background: var(--amber); }
+ &::-moz-progress-bar { background: var(--amber); }
+ }
+ }
+
+ &__active-icon {
+ position: absolute;
+ inset-inline-end: $space-5;
+ inset-block-start: 58px;
+ display: grid;
+ width: 40px;
+ height: 40px;
+ place-items: center;
+ border: 1px solid var(--border-strong);
+ border-radius: $radius-md;
+ background: var(--surface-2);
+
+ &.is-cyan { color: var(--cyan); }
+ &.is-amber { color: var(--amber); }
+ }
+
+ &__progress-copy {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ margin-bottom: $space-2;
+ color: var(--text-faint);
+ font-family: var(--mono);
+ font-size: 10px;
+
+ strong { color: var(--text); }
+ }
+
+ &__steps {
+ min-height: 150px;
+ margin: 0;
+ padding: $space-4 $space-5;
+ list-style: none;
+ background: color-mix(in srgb, var(--surface) 97%, transparent);
+
+ li {
+ position: relative;
+ display: grid;
+ grid-template-columns: 24px minmax(0, 1fr);
+ gap: $space-3;
+ padding: $space-2 0 $space-3;
+ color: var(--text-ghost);
+
+ &:not(:last-child)::after {
+ position: absolute;
+ inset-inline-start: 11px;
+ inset-block-start: 31px;
+ width: 1px;
+ height: calc(100% - 21px);
+ background: var(--border-soft);
+ content: '';
+ }
+
+ &.is-current { color: var(--text); }
+ &.is-done { color: var(--text-muted); }
+
+ strong {
+ display: block;
+ padding-top: 2px;
+ font-size: $font-size-sm;
+ font-weight: $font-weight-semibold;
+ }
+
+ p {
+ margin: $space-1 0 0;
+ color: var(--text-faint);
+ font-size: 11px;
+ line-height: 1.45;
+ }
+ }
+ }
+
+ &__step-marker {
+ position: relative;
+ z-index: 1;
+ display: grid;
+ width: 24px;
+ height: 24px;
+ place-items: center;
+ border: 1px solid var(--border-strong);
+ border-radius: 50%;
+ background: var(--surface);
+ color: var(--text-ghost);
+ font-family: var(--mono);
+ font-size: 9px;
+
+ .is-current & {
+ border-color: var(--amber);
+ color: var(--amber);
+ box-shadow: 0 0 0 3px color-mix(in srgb, var(--amber) 12%, transparent);
+ }
+
+ .is-done & {
+ border-color: var(--green);
+ background: color-mix(in srgb, var(--green) 12%, var(--surface));
+ color: var(--green);
+ }
+ }
+
+ &__next {
+ margin: 0 $space-4 $space-4;
+ padding: $space-4;
+ border: 1px solid color-mix(in srgb, var(--amber) 42%, var(--border));
+ border-inline-start-width: 3px;
+ border-radius: $radius-md;
+ background: color-mix(in srgb, var(--amber) 9%, var(--surface));
+
+ > span {
+ display: block;
+ margin-bottom: $space-1;
+ color: var(--amber);
+ font-family: var(--mono);
+ font-size: 9px;
+ font-weight: $font-weight-semibold;
+ letter-spacing: 0.12em;
+ text-transform: uppercase;
+ }
+
+ > strong { color: var(--text); font-size: $font-size-sm; }
+ p { margin: $space-2 0 $space-3; color: var(--text-muted); font-size: 12px; line-height: 1.5; }
+ .btn { width: 100%; justify-content: space-between; }
+ }
+
+ &__footer {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: $space-3;
+ padding: $space-2 $space-4;
+ border-top: 1px solid var(--border-soft);
+ background: var(--surface-2);
+
+ > span { color: var(--text-ghost); font-family: var(--mono); font-size: 9px; }
+ }
+}
+
+.walkthrough-card {
+ display: grid;
+ grid-template-columns: 38px minmax(0, 1fr);
+ gap: $space-3;
+ padding: $space-4;
+ border: 1px solid var(--border);
+ border-radius: $radius-md;
+ background: var(--surface-2);
+ transition: border-color 150ms ease, transform 150ms ease;
+
+ &:hover { border-color: var(--border-strong); transform: translateY(-1px); }
+
+ &__icon {
+ display: grid;
+ width: 38px;
+ height: 38px;
+ place-items: center;
+ border: 1px solid var(--border);
+ border-radius: $radius-sm;
+ background: var(--surface);
+ }
+
+ &--cyan &__icon { color: var(--cyan); }
+ &--amber &__icon { color: var(--amber); }
+
+ &__meta {
+ display: flex;
+ min-height: 20px;
+ align-items: center;
+ gap: $space-2;
+
+ > span:first-child {
+ display: inline-flex;
+ align-items: center;
+ gap: $space-1;
+ margin-inline-end: auto;
+ color: var(--text-ghost);
+ font-family: var(--mono);
+ font-size: 9px;
+ }
+ }
+
+ h3 { margin: $space-2 0 $space-1; color: var(--text); font-size: $font-size-sm; }
+ p { margin: 0 0 $space-3; color: var(--text-faint); font-size: 11px; line-height: 1.45; }
+}
+
+.is-walkthrough-target {
+ position: relative;
+ z-index: 2;
+ outline: 2px solid var(--amber) !important;
+ outline-offset: 4px;
+ animation: walkthrough-target-pulse 1.8s ease-in-out infinite;
+}
+
+@keyframes walkthrough-enter {
+ from { opacity: 0; transform: translateY(8px) scale(0.985); }
+ to { opacity: 1; transform: translateY(0) scale(1); }
+}
+
+@keyframes walkthrough-target-pulse {
+ 0%, 100% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--amber) 0%, transparent); }
+ 50% { box-shadow: 0 0 0 7px color-mix(in srgb, var(--amber) 14%, transparent); }
+}
+
+@media (max-width: $breakpoint-md) {
+ .walkthrough-shell {
+ inset-inline: $space-3;
+ inset-block-end: calc(#{$space-3} + env(safe-area-inset-bottom));
+
+ &__launcher { margin-inline-start: auto; }
+ }
+
+ .walkthrough-hub {
+ width: 100%;
+ max-height: min(78vh, 700px);
+ border-radius: $radius-lg $radius-lg 0 0;
+ }
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .walkthrough-hub,
+ .is-walkthrough-target { animation: none; }
+}
diff --git a/frontend/src/styles/main.scss b/frontend/src/styles/main.scss
index cd4a577e..af143ba8 100644
--- a/frontend/src/styles/main.scss
+++ b/frontend/src/styles/main.scss
@@ -69,6 +69,7 @@
@import 'components/_command-palette';
@import 'components/_logs-drawer';
@import 'components/_operations-dock';
+@import 'components/_walkthroughs';
@import 'components/_ai-assistant';
@import 'components/_ui';
@import 'components/_staging-banner';