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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat: add guided operator walkthroughs
Juan Denisd6950cc40f4a
diff --git a/backend/app/api/walkthroughs.py b/backend/app/api/walkthroughs.pynew file mode 100644index 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}), 200diff --git a/backend/app/core_blueprints.py b/backend/app/core_blueprints.pyindex 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.pynew file mode 100644index 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 valuediff --git a/backend/tests/test_core_blueprint_registry.py b/backend/tests/test_core_blueprint_registry.pyindex 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 Pathfrom app.core_blueprints import CORE_BLUEPRINTS-EXPECTED_CORE_BLUEPRINT_COUNT = 110+EXPECTED_CORE_BLUEPRINT_COUNT = 111EXPECTED_MANIFEST_SHA256 = (- '8d70318fa935817c1b92b03f186c75c8c9cd6eb7aa3483e0bc44b735fd5c5722'+ '560d72b4a31a6ad7ac8f1c9dd906000c7fd3c315f9aaf7e2df61fa98fb782d6e')diff --git a/backend/tests/test_route_authz_sweep.py b/backend/tests/test_route_authz_sweep.pyindex 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.pynew file mode 100644index 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.jsxnew file mode 100644index 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.jsxindex 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.jsxnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsonindex 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.jsxindex 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.jsxindex 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.jsxindex 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.jsxindex 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 }) => (<buttonkey={mode}diff --git a/frontend/src/pages/new-service/useNewServiceForm.js b/frontend/src/pages/new-service/useNewServiceForm.jsindex 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.mjsnew file mode 100644index 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.jsindex 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.scssnew file mode 100644index 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.scssindex 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';