orbital-command 0.2.0 → 0.3.0

package/dist/server/shared/workflow-engine.test.js

@@ -0,0 +1,302 @@
+import { describe, it, expect } from 'vitest';
+import { WorkflowEngine } from './workflow-engine.js';
+import { MINIMAL_CONFIG, CONFIG_WITH_HOOKS, DEFAULT_CONFIG, INVALID_CONFIGS } from './__fixtures__/workflow-configs.js';
+// ─── Constructor ──────────────────────────────────────────────
+describe('WorkflowEngine', () => {
+    describe('constructor', () => {
+        it('creates engine from minimal config', () => {
+            const engine = new WorkflowEngine(MINIMAL_CONFIG);
+            expect(engine.getConfig().name).toBe('Minimal');
+        });
+        it('throws on empty lists', () => {
+            expect(() => new WorkflowEngine(INVALID_CONFIGS.noLists)).toThrow('at least 1 list');
+        });
+        it('throws on empty edges', () => {
+            expect(() => new WorkflowEngine(INVALID_CONFIGS.noEdges)).toThrow('at least 1 edge');
+        });
+        it('throws on two entry points', () => {
+            expect(() => new WorkflowEngine(INVALID_CONFIGS.twoEntryPoints)).toThrow('exactly 1 entry point, found 2');
+        });
+        it('throws on zero entry points', () => {
+            expect(() => new WorkflowEngine(INVALID_CONFIGS.zeroEntryPoints)).toThrow('exactly 1 entry point, found 0');
+        });
+    });
+    // ─── reload() ─────────────────────────────────────────────────
+    describe('reload()', () => {
+        it('replaces config and rebuilds indexes', () => {
+            const engine = new WorkflowEngine(MINIMAL_CONFIG);
+            expect(engine.getLists()).toHaveLength(2);
+            engine.reload(CONFIG_WITH_HOOKS);
+            expect(engine.getLists()).toHaveLength(4);
+            expect(engine.getConfig().name).toBe('With Hooks');
+        });
+        it('throws on invalid config during reload', () => {
+            const engine = new WorkflowEngine(MINIMAL_CONFIG);
+            expect(() => engine.reload(INVALID_CONFIGS.noLists)).toThrow();
+        });
+    });
+    // ─── List Queries ─────────────────────────────────────────────
+    describe('list queries', () => {
+        const engine = new WorkflowEngine(DEFAULT_CONFIG);
+        it('getLists() returns sorted by order', () => {
+            const lists = engine.getLists();
+            for (let i = 1; i < lists.length; i++) {
+                expect(lists[i].order).toBeGreaterThanOrEqual(lists[i - 1].order);
+            }
+        });
+        it('getList() returns correct list or undefined', () => {
+            expect(engine.getList('icebox')?.label).toBe('Icebox');
+            expect(engine.getList('nonexistent')).toBeUndefined();
+        });
+        it('getEntryPoint() returns the entry point', () => {
+            const entry = engine.getEntryPoint();
+            expect(entry.isEntryPoint).toBe(true);
+            expect(entry.id).toBe('icebox');
+        });
+        it('getBatchLists() filters by supportsBatch', () => {
+            const batch = engine.getBatchLists();
+            expect(batch.length).toBeGreaterThan(0);
+            expect(batch.every(l => l.supportsBatch)).toBe(true);
+        });
+        it('getSprintLists() filters by supportsSprint', () => {
+            const sprint = engine.getSprintLists();
+            expect(sprint.length).toBeGreaterThan(0);
+            expect(sprint.every(l => l.supportsSprint)).toBe(true);
+        });
+        it('getBoardColumns() returns id, label, color tuples sorted by order', () => {
+            const cols = engine.getBoardColumns();
+            expect(cols[0]).toEqual({ id: 'icebox', label: 'Icebox', color: expect.any(String) });
+            for (let i = 1; i < cols.length; i++) {
+                const prevOrder = engine.getList(cols[i - 1].id).order;
+                const currOrder = engine.getList(cols[i].id).order;
+                expect(currOrder).toBeGreaterThanOrEqual(prevOrder);
+            }
+        });
+    });
+    // ─── Edge Queries ─────────────────────────────────────────────
+    describe('edge queries', () => {
+        const engine = new WorkflowEngine(DEFAULT_CONFIG);
+        it('findEdge() returns edge or undefined', () => {
+            const edge = engine.findEdge('icebox', 'planning');
+            expect(edge).toBeDefined();
+            expect(edge.direction).toBe('forward');
+            expect(engine.findEdge('icebox', 'main')).toBeUndefined();
+        });
+        it('isValidTransition() returns boolean', () => {
+            expect(engine.isValidTransition('icebox', 'planning')).toBe(true);
+            expect(engine.isValidTransition('icebox', 'main')).toBe(false);
+        });
+        it('getValidTargets() returns target IDs', () => {
+            const targets = engine.getValidTargets('icebox');
+            expect(targets).toContain('planning');
+        });
+        it('getValidTargets() returns empty for unknown status', () => {
+            expect(engine.getValidTargets('nonexistent')).toEqual([]);
+        });
+        it('getAllEdges() returns all edges', () => {
+            expect(engine.getAllEdges().length).toBe(DEFAULT_CONFIG.edges.length);
+        });
+        it('getEdgesByDirection() filters correctly', () => {
+            const forward = engine.getEdgesByDirection('forward');
+            expect(forward.every(e => e.direction === 'forward')).toBe(true);
+            const backward = engine.getEdgesByDirection('backward');
+            expect(backward.every(e => e.direction === 'backward')).toBe(true);
+            expect(backward.length).toBeGreaterThan(0);
+        });
+    });
+    // ─── validateTransition() ─────────────────────────────────────
+    describe('validateTransition()', () => {
+        const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+        it('rejects invalid target status', () => {
+            const result = engine.validateTransition('backlog', 'nonexistent', 'patch');
+            expect(result).toEqual({ ok: false, error: expect.stringContaining('Invalid status'), code: 'INVALID_STATUS' });
+        });
+        it('bulk-sync always succeeds', () => {
+            expect(engine.validateTransition('shipped', 'backlog', 'bulk-sync')).toEqual({ ok: true });
+        });
+        it('rollback always succeeds', () => {
+            expect(engine.validateTransition('shipped', 'backlog', 'rollback')).toEqual({ ok: true });
+        });
+        it('same status is always ok', () => {
+            expect(engine.validateTransition('backlog', 'backlog', 'patch')).toEqual({ ok: true });
+        });
+        it('rejects non-existent edge', () => {
+            const result = engine.validateTransition('backlog', 'shipped', 'patch');
+            expect(result).toEqual({ ok: false, error: expect.stringContaining('not allowed'), code: 'INVALID_TRANSITION' });
+        });
+        it('rejects patch context on dispatchOnly edge', () => {
+            const result = engine.validateTransition('backlog', 'active', 'patch');
+            expect(result).toEqual({ ok: false, error: expect.stringContaining('requires dispatch'), code: 'DISPATCH_REQUIRED' });
+        });
+        it('allows dispatch context on dispatchOnly edge', () => {
+            expect(engine.validateTransition('backlog', 'active', 'dispatch')).toEqual({ ok: true });
+        });
+    });
+    // ─── Status Helpers ───────────────────────────────────────────
+    describe('status helpers', () => {
+        const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+        it('isValidStatus() returns true for known, false for unknown', () => {
+            expect(engine.isValidStatus('backlog')).toBe(true);
+            expect(engine.isValidStatus('nonexistent')).toBe(false);
+        });
+        it('isTerminalStatus() returns true for terminal statuses', () => {
+            expect(engine.isTerminalStatus('shipped')).toBe(true);
+            expect(engine.isTerminalStatus('backlog')).toBe(false);
+        });
+        it('getStatusOrder() returns numeric order or -1', () => {
+            expect(engine.getStatusOrder('backlog')).toBe(0);
+            expect(engine.getStatusOrder('active')).toBe(1);
+            expect(engine.getStatusOrder('unknown')).toBe(-1);
+        });
+        it('isForwardMovement() compares orders', () => {
+            expect(engine.isForwardMovement('backlog', 'active')).toBe(true);
+            expect(engine.isForwardMovement('active', 'backlog')).toBe(false);
+            expect(engine.isForwardMovement('active', 'active')).toBe(false);
+        });
+    });
+    // ─── Commands ─────────────────────────────────────────────────
+    describe('commands', () => {
+        const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+        it('buildCommand() replaces {id} with scope ID', () => {
+            const edge = engine.findEdge('backlog', 'active');
+            expect(engine.buildCommand(edge, 42)).toBe('/scope-implement 42');
+        });
+        it('buildCommand() returns null when edge has no command', () => {
+            const edge = engine.findEdge('active', 'backlog');
+            expect(engine.buildCommand(edge, 1)).toBeNull();
+        });
+        it('isAllowedCommand() checks prefix list', () => {
+            expect(engine.isAllowedCommand('/scope-implement 42')).toBe(true);
+            expect(engine.isAllowedCommand('/git-main')).toBe(true);
+            expect(engine.isAllowedCommand('/unknown-command')).toBe(false);
+        });
+    });
+    // ─── Batch / Sprint ───────────────────────────────────────────
+    describe('batch/sprint', () => {
+        const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+        it('getBatchTargetStatus() finds first forward dispatchOnly edge target', () => {
+            expect(engine.getBatchTargetStatus('backlog')).toBe('active');
+        });
+        it('getBatchTargetStatus() returns undefined for no match', () => {
+            expect(engine.getBatchTargetStatus('shipped')).toBeUndefined();
+        });
+        it('getBatchCommand() strips {id} placeholder', () => {
+            expect(engine.getBatchCommand('backlog')).toBe('/scope-implement');
+        });
+        it('getBatchCommand() returns undefined for no match', () => {
+            expect(engine.getBatchCommand('shipped')).toBeUndefined();
+        });
+    });
+    // ─── inferStatus() ────────────────────────────────────────────
+    describe('inferStatus()', () => {
+        const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+        it('returns null when no rules match event type', () => {
+            expect(engine.inferStatus('UNKNOWN_EVENT', 'backlog', {})).toBeNull();
+        });
+        it('matches AGENT_STARTED to active status', () => {
+            expect(engine.inferStatus('AGENT_STARTED', 'backlog', {})).toBe('active');
+        });
+        it('forwardOnly guard prevents backward movement', () => {
+            // active (order 1) → active (order 1) — not forward, returns null
+            expect(engine.inferStatus('AGENT_STARTED', 'active', {})).toBeNull();
+        });
+        it('handles SCOPE_STATUS_CHANGED with dataField resolution', () => {
+            const result = engine.inferStatus('SCOPE_STATUS_CHANGED', 'backlog', { to: 'active' });
+            expect(result).toBe('active');
+        });
+        it('SCOPE_STATUS_CHANGED with dataField returns null for empty value', () => {
+            expect(engine.inferStatus('SCOPE_STATUS_CHANGED', 'backlog', { to: '' })).toBeNull();
+        });
+        it('handles dispatchResolution conditions', () => {
+            const result = engine.inferStatus('AGENT_COMPLETED', 'active', { outcome: 'success' });
+            expect(result).toEqual({ dispatchResolution: true, resolution: 'completed' });
+        });
+        it('handles dispatchResolution with failure outcome', () => {
+            const result = engine.inferStatus('AGENT_COMPLETED', 'active', { outcome: 'failure' });
+            expect(result).toEqual({ dispatchResolution: true, resolution: 'failed' });
+        });
+    });
+    // ─── Generation ───────────────────────────────────────────────
+    describe('generation', () => {
+        const engine = new WorkflowEngine(MINIMAL_CONFIG);
+        it('generateCSSVariables() produces correct format', () => {
+            const css = engine.generateCSSVariables();
+            expect(css).toContain('--status-todo:');
+            expect(css).toContain('--status-done:');
+        });
+        it('generateShellManifest() produces valid bash structure', () => {
+            const manifest = engine.generateShellManifest();
+            expect(manifest).toContain('#!/bin/bash');
+            expect(manifest).toContain('WORKFLOW_STATUSES="todo done"');
+            expect(manifest).toContain('WORKFLOW_ENTRY_STATUS="todo"');
+            expect(manifest).toContain('WORKFLOW_TERMINAL_STATUSES="done"');
+            expect(manifest).toContain('WORKFLOW_EDGES=(');
+            expect(manifest).toContain('is_valid_status()');
+        });
+    });
+    // ─── Git / Lifecycle ──────────────────────────────────────────
+    describe('git/lifecycle', () => {
+        const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+        it('getListByGitBranch() finds the right list', () => {
+            expect(engine.getListByGitBranch('main')?.id).toBe('shipped');
+        });
+        it('getListByGitBranch() returns undefined for unknown branch', () => {
+            expect(engine.getListByGitBranch('feature/foo')).toBeUndefined();
+        });
+        it('getGitBranch() returns branch or undefined', () => {
+            expect(engine.getGitBranch('shipped')).toBe('main');
+            expect(engine.getGitBranch('backlog')).toBeUndefined();
+        });
+        it('getSessionKey() returns session key or undefined', () => {
+            expect(engine.getSessionKey('active')).toBe('implementScope');
+            expect(engine.getSessionKey('backlog')).toBeUndefined();
+        });
+        it('getActiveHooksForList() returns empty for list without activeHooks', () => {
+            expect(engine.getActiveHooksForList('backlog')).toEqual([]);
+        });
+        it('getAgentsForEdge() returns agents array', () => {
+            expect(engine.getAgentsForEdge('backlog', 'active')).toEqual(['architect']);
+        });
+        it('getAgentsForEdge() returns empty for edge without agents', () => {
+            expect(engine.getAgentsForEdge('active', 'backlog')).toEqual([]);
+        });
+    });
+    // ─── Hooks ────────────────────────────────────────────────────
+    describe('hooks', () => {
+        const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+        it('getHooksForEdge() resolves hook IDs to hook objects', () => {
+            const hooks = engine.getHooksForEdge('backlog', 'active');
+            expect(hooks).toHaveLength(1);
+            expect(hooks[0].id).toBe('blocker-check');
+        });
+        it('getHooksForEdge() returns empty for edge without hooks', () => {
+            const engine2 = new WorkflowEngine(MINIMAL_CONFIG);
+            expect(engine2.getHooksForEdge('todo', 'done')).toEqual([]);
+        });
+        it('getAllHooks() returns all hooks', () => {
+            expect(engine.getAllHooks()).toHaveLength(4);
+        });
+        it('getHookEnforcement() maps category correctly', () => {
+            const guard = engine.getAllHooks().find(h => h.category === 'guard');
+            expect(engine.getHookEnforcement(guard)).toBe('blocker');
+            const gate = engine.getAllHooks().find(h => h.category === 'gate');
+            expect(engine.getHookEnforcement(gate)).toBe('advisor');
+        });
+        it('getHooksByCategory() filters by category', () => {
+            const guards = engine.getHooksByCategory('guard');
+            expect(guards.every(h => h.category === 'guard')).toBe(true);
+            expect(guards.length).toBe(1);
+        });
+    });
+    // ─── Config Access ────────────────────────────────────────────
+    describe('config access', () => {
+        it('getBranchingMode() returns trunk by default', () => {
+            const engine = new WorkflowEngine(MINIMAL_CONFIG);
+            expect(engine.getBranchingMode()).toBe('trunk');
+        });
+        it('getBranchingMode() returns configured value', () => {
+            const engine = new WorkflowEngine(DEFAULT_CONFIG);
+            expect(engine.getBranchingMode()).toBe('trunk');
+        });
+    });
+});

package/dist/server/shared/workflow-normalizer.js

@@ -0,0 +1,101 @@
+// ─── Phase Mapping ──────────────────────────────────────────
+/** Infer a list's semantic phase from its properties. */
+function inferPhase(list, terminalStatuses) {
+    // Explicit phase takes priority
+    if (list.phase)
+        return list.phase;
+    // Terminal statuses or lists with a git branch → shipped
+    if (terminalStatuses.includes(list.id) || list.gitBranch)
+        return 'shipped';
+    // Entry points and planning group → queued
+    if (list.isEntryPoint)
+        return 'queued';
+    if (list.group === 'planning')
+        return 'queued';
+    // Session key inference
+    if (list.sessionKey) {
+        if (list.sessionKey.toLowerCase().includes('implement'))
+            return 'active';
+        if (list.sessionKey.toLowerCase().includes('review') ||
+            list.sessionKey.toLowerCase().includes('gate') ||
+            list.sessionKey.toLowerCase().includes('commit') ||
+            list.sessionKey.toLowerCase().includes('verify'))
+            return 'review';
+        if (list.sessionKey.toLowerCase().includes('push') ||
+            list.sessionKey.toLowerCase().includes('deploy'))
+            return 'shipped';
+        if (list.sessionKey.toLowerCase().includes('create') ||
+            list.sessionKey.toLowerCase().includes('scope'))
+            return 'queued';
+    }
+    // Group-based inference
+    if (list.group === 'development') {
+        // Lists earlier in development → active, later → review
+        return list.order <= 3 ? 'active' : 'review';
+    }
+    if (list.group === 'active')
+        return 'active';
+    if (list.group?.startsWith('deploy'))
+        return 'shipped';
+    if (list.group === 'main')
+        return 'shipped';
+    // Default: use order-based heuristic
+    return 'queued';
+}
+/** The four normalized columns. */
+export const PHASE_COLUMNS = [
+    { phase: 'queued', label: 'Queued', order: 0 },
+    { phase: 'active', label: 'Active', order: 1 },
+    { phase: 'review', label: 'Review', order: 2 },
+    { phase: 'shipped', label: 'Shipped', order: 3 },
+];
+/**
+ * Maps workflow lists to semantic phases for the All Projects board.
+ *
+ * Each WorkflowEngine's lists get mapped to one of four phases.
+ * When all projects share the same workflow, the board shows full columns.
+ * When workflows differ, the board uses these normalized phases.
+ */
+export class WorkflowNormalizer {
+    engine;
+    phaseMap;
+    constructor(engine) {
+        this.engine = engine;
+        this.phaseMap = new Map();
+        const lists = engine.getLists();
+        const terminalStatuses = engine.getConfig().terminalStatuses ?? [];
+        for (const list of lists) {
+            this.phaseMap.set(list.id, inferPhase(list, terminalStatuses));
+        }
+    }
+    /** Get the phase for a list/status ID. */
+    getPhase(listId) {
+        return this.phaseMap.get(listId) ?? 'queued';
+    }
+    /** Get all lists that map to a given phase. */
+    getListsForPhase(phase) {
+        return this.engine.getLists().filter(l => this.getPhase(l.id) === phase);
+    }
+    /** Get the full phase map. */
+    getPhaseMap() {
+        return this.phaseMap;
+    }
+    /**
+     * Find valid workflow transitions from `currentListId` whose target
+     * maps to `targetPhase`. Used for DnD in the All Projects phase view.
+     */
+    resolveNormalizedTransition(currentListId, targetPhase) {
+        const config = this.engine.getConfig();
+        return config.edges.filter(edge => edge.from === currentListId && this.getPhase(edge.to) === targetPhase);
+    }
+}
+/**
+ * Check if all engines share the same workflow (same list IDs in same order).
+ * When true, the All Projects board can show full columns instead of phases.
+ */
+export function allEnginesMatch(engines) {
+    if (engines.length <= 1)
+        return true;
+    const firstLists = engines[0].getLists().map(l => l.id).join(',');
+    return engines.every(e => e.getLists().map(l => l.id).join(',') === firstLists);
+}

package/dist/server/shared/workflow-normalizer.test.js

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import { WorkflowNormalizer, PHASE_COLUMNS, allEnginesMatch } from './workflow-normalizer.js';
+import { WorkflowEngine } from './workflow-engine.js';
+import { DEFAULT_CONFIG, MINIMAL_CONFIG } from './__fixtures__/workflow-configs.js';
+describe('PHASE_COLUMNS', () => {
+    it('has 4 entries in correct order', () => {
+        expect(PHASE_COLUMNS).toHaveLength(4);
+        expect(PHASE_COLUMNS.map(c => c.phase)).toEqual(['queued', 'active', 'review', 'shipped']);
+        expect(PHASE_COLUMNS.map(c => c.order)).toEqual([0, 1, 2, 3]);
+    });
+});
+describe('WorkflowNormalizer', () => {
+    const engine = new WorkflowEngine(DEFAULT_CONFIG);
+    const normalizer = new WorkflowNormalizer(engine);
+    describe('phase inference with default config', () => {
+        it('entry point (icebox) maps to queued', () => {
+            expect(normalizer.getPhase('icebox')).toBe('queued');
+        });
+        it('planning group list maps to queued', () => {
+            expect(normalizer.getPhase('planning')).toBe('queued');
+        });
+        it('backlog (planning group with reviewScope session) maps to queued', () => {
+            expect(normalizer.getPhase('backlog')).toBe('queued');
+        });
+        it('implementing (sessionKey includes "implement") maps to active', () => {
+            expect(normalizer.getPhase('implementing')).toBe('active');
+        });
+        it('review (sessionKey includes "review") maps to review', () => {
+            expect(normalizer.getPhase('review')).toBe('review');
+        });
+        it('completed (sessionKey "commit") maps to review', () => {
+            expect(normalizer.getPhase('completed')).toBe('review');
+        });
+        it('main (terminal status with gitBranch) maps to shipped', () => {
+            expect(normalizer.getPhase('main')).toBe('shipped');
+        });
+    });
+    describe('getPhase()', () => {
+        it('returns queued for unknown list ID (default)', () => {
+            expect(normalizer.getPhase('nonexistent')).toBe('queued');
+        });
+    });
+    describe('getListsForPhase()', () => {
+        it('returns all lists for a given phase', () => {
+            const queued = normalizer.getListsForPhase('queued');
+            expect(queued.length).toBeGreaterThan(0);
+            for (const list of queued) {
+                expect(normalizer.getPhase(list.id)).toBe('queued');
+            }
+        });
+        it('shipped phase includes main', () => {
+            const shipped = normalizer.getListsForPhase('shipped');
+            expect(shipped.some(l => l.id === 'main')).toBe(true);
+        });
+    });
+    describe('getPhaseMap()', () => {
+        it('returns a map covering all lists', () => {
+            const map = normalizer.getPhaseMap();
+            const lists = engine.getLists();
+            for (const list of lists) {
+                expect(map.has(list.id)).toBe(true);
+            }
+        });
+    });
+    describe('resolveNormalizedTransition()', () => {
+        it('returns edges from a list to a target phase', () => {
+            // icebox → planning is forward, planning maps to queued
+            const edges = normalizer.resolveNormalizedTransition('icebox', 'queued');
+            expect(edges.length).toBeGreaterThan(0);
+            expect(edges[0].from).toBe('icebox');
+        });
+        it('returns empty when no edges match', () => {
+            // icebox has no edge to any shipped-phase list
+            const edges = normalizer.resolveNormalizedTransition('icebox', 'shipped');
+            expect(edges).toEqual([]);
+        });
+    });
+});
+describe('allEnginesMatch()', () => {
+    it('returns true for empty array', () => {
+        expect(allEnginesMatch([])).toBe(true);
+    });
+    it('returns true for single engine', () => {
+        expect(allEnginesMatch([new WorkflowEngine(DEFAULT_CONFIG)])).toBe(true);
+    });
+    it('returns true when all engines have same lists', () => {
+        const engines = [
+            new WorkflowEngine(DEFAULT_CONFIG),
+            new WorkflowEngine(DEFAULT_CONFIG),
+        ];
+        expect(allEnginesMatch(engines)).toBe(true);
+    });
+    it('returns false when engines differ', () => {
+        const engines = [
+            new WorkflowEngine(DEFAULT_CONFIG),
+            new WorkflowEngine(MINIMAL_CONFIG),
+        ];
+        expect(allEnginesMatch(engines)).toBe(false);
+    });
+});

package/dist/server/src/components/onboarding/tour-steps.js

@@ -0,0 +1,84 @@
+export const TOUR_STEPS = [
+    // Kanban page steps
+    {
+        id: 'welcome',
+        target: 'nav-kanban',
+        title: 'Welcome to Orbital Command',
+        description: 'This is your project management dashboard for Claude Code projects. Let\'s take a quick tour of what everything does.',
+        page: '/',
+    },
+    {
+        id: 'kanban-board',
+        target: 'kanban-board',
+        title: 'Kanban Board',
+        description: 'Your scopes are organized into columns that represent workflow stages. Each column maps to a status in your workflow configuration.',
+        page: '/',
+        placement: 'right',
+        maxSpotlightWidth: 800,
+    },
+    {
+        id: 'kanban-column',
+        target: 'kanban-column',
+        title: 'Workflow Columns',
+        description: 'Columns are driven by your workflow DAG — transitions between statuses are defined as edges. Drag scopes between columns to update their status.',
+        page: '/',
+        optional: true,
+        placement: 'bottom',
+    },
+    {
+        id: 'scope-card',
+        target: 'scope-card',
+        title: 'Scope Cards',
+        description: 'Each card represents a scope — a unit of work with phases, success criteria, and a definition of done. Click a card to see its full details.',
+        page: '/',
+        optional: true,
+        placement: 'bottom',
+    },
+    // Primitives page
+    {
+        id: 'nav-primitives',
+        target: 'nav-primitives',
+        title: 'Primitives',
+        description: 'View and manage the building blocks of your project — hooks, skills, agents, and workflow presets that power your Claude Code setup.',
+        page: '/primitives',
+    },
+    // Guards page
+    {
+        id: 'nav-guards',
+        target: 'nav-guards',
+        title: 'Guards',
+        description: 'Quality gates and enforcement rules that run before transitions. Configure type checks, tests, linting, and custom validation commands.',
+        page: '/guards',
+    },
+    // Repo page
+    {
+        id: 'nav-repo',
+        target: 'nav-repo',
+        title: 'Repo',
+        description: 'Source control integration — view branches, recent commits, and GitHub connection status for your project.',
+        page: '/repo',
+    },
+    // Sessions page
+    {
+        id: 'nav-sessions',
+        target: 'nav-sessions',
+        title: 'Sessions',
+        description: 'Track Claude Code agent sessions — see what\'s running, review session history, and monitor dispatch progress in real time.',
+        page: '/sessions',
+    },
+    // Workflow page
+    {
+        id: 'nav-workflow',
+        target: 'nav-workflow',
+        title: 'Workflow',
+        description: 'The visual DAG editor for your workflow configuration. Define statuses, transitions, hooks, and event inference rules that drive the Kanban board.',
+        page: '/workflow',
+    },
+    // Settings
+    {
+        id: 'nav-settings',
+        target: 'nav-settings',
+        title: 'Settings',
+        description: 'Customize appearance, font, zoom level, and other preferences. You can restart this tour anytime from here.',
+    },
+];