@compilr-dev/cli 0.4.0

package/dist/ui/tutorial-overlay.js

@@ -0,0 +1,936 @@
+/**
+ * Tutorial Overlay
+ *
+ * Interactive tutorial that guides users through the compilr.dev workflow.
+ * Supports guided sequential tour and topic-based navigation.
+ */
+import * as terminal from './terminal.js';
+import { getStyles } from '../themes/index.js';
+// =============================================================================
+// Helper
+// =============================================================================
+/**
+ * Strip ANSI codes from string to get visible length
+ */
+function stripAnsi(str) {
+    // eslint-disable-next-line no-control-regex
+    return str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');
+}
+function getBorder() {
+    const s = getStyles();
+    const cols = terminal.getTerminalWidth();
+    return s.muted('─'.repeat(Math.max(1, cols - 1)));
+}
+// =============================================================================
+// Content
+// =============================================================================
+function buildTopics() {
+    const s = getStyles();
+    return [
+        // =========================================================================
+        // Topic 1: Workflow Overview
+        // =========================================================================
+        {
+            id: 'overview',
+            name: 'Workflow Overview',
+            description: 'The philosophy and stages',
+            pages: [
+                {
+                    title: 'Philosophy',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('compilr.dev')} is built on five core principles:`,
+                        '',
+                        `    ${s.primary('1. Structured')}`,
+                        `       Follow an organized workflow instead of ad-hoc coding.`,
+                        `       Every project has clear phases and documentation.`,
+                        '',
+                        `    ${s.primary('2. Disciplined')}`,
+                        `       Move through clear phases from design to delivery.`,
+                        `       Don't skip steps - each builds on the previous.`,
+                        '',
+                        `    ${s.primary('3. Intentional')}`,
+                        `       Every feature starts with requirements, not code.`,
+                        `       Know what you're building before you build it.`,
+                        '',
+                    ],
+                },
+                {
+                    title: 'Philosophy (continued)',
+                    lines: [
+                        '',
+                        `    ${s.primary('4. Engineering-First')}`,
+                        `       Follow best practices: testing, documentation, code review.`,
+                        `       Build software that's maintainable long-term.`,
+                        '',
+                        `    ${s.primary('5. Flexible')}`,
+                        `       Adapt the workflow to your needs.`,
+                        `       Use what works, skip what doesn't.`,
+                        '',
+                        `  The AI assistant guides you through each stage, helping you build`,
+                        `  projects with ${s.primary('structure')} and ${s.primary('discipline')} - not just generating random code.`,
+                        '',
+                        `  ${s.muted('The goal: sustainable development with AI assistance.')}`,
+                        '',
+                    ],
+                },
+                {
+                    title: 'The Workflow Stages',
+                    lines: [
+                        '',
+                        `  The development workflow has five main stages:`,
+                        '',
+                        `    ${s.primary('/init')}      Set up your project structure`,
+                        `               Creates COMPILR.md, backlog.md, and configuration`,
+                        '',
+                        `    ${s.primary('/design')}    Gather requirements and create a PRD`,
+                        `               Comprehensive planning through conversation`,
+                        '',
+                        `    ${s.primary('/backlog')}   Manage your work items`,
+                        `               Prioritize, track status, break down tasks`,
+                        '',
+                        `    ${s.primary('/build')}     Implement features from the backlog`,
+                        `               AI-assisted coding with your approval`,
+                        '',
+                        `    ${s.secondary('Iterate')}     Refine and improve continuously`,
+                        `               Use /refine, /arch, /prd to evolve the project`,
+                        '',
+                    ],
+                },
+            ],
+        },
+        // =========================================================================
+        // Topic 2: Initialize
+        // =========================================================================
+        {
+            id: 'init',
+            name: 'Initialize',
+            description: 'Setting up a new project',
+            pages: [
+                {
+                    title: '/init Command',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('/init')} creates your project foundation through an 8-step wizard.`,
+                        '',
+                        `  ${s.secondary('What it creates:')}`,
+                        '',
+                        `    ${s.success('+')} Project directory with proper structure`,
+                        `    ${s.success('+')} ${s.primary('COMPILR.md')} - Context file for the AI assistant`,
+                        `    ${s.success('+')} ${s.primary('backlog.md')} - Work item tracking`,
+                        `    ${s.success('+')} ${s.primary('.compilr/config.json')} - Project configuration`,
+                        `    ${s.success('+')} Tech stack setup based on your choices`,
+                        '',
+                        `  ${s.secondary('The wizard asks about:')}`,
+                        `    - Project name and description`,
+                        `    - Project type (web, api, cli, fullstack)`,
+                        `    - Tech stack preferences`,
+                        `    - Documentation setup (single or two repos)`,
+                        '',
+                    ],
+                },
+                {
+                    title: '/init - Setup Options',
+                    lines: [
+                        '',
+                        `  ${s.secondary('Single Repository Setup')}`,
+                        `    Everything in one directory: code, docs, and backlog.`,
+                        `    Best for: small projects, personal projects, quick starts.`,
+                        '',
+                        `  ${s.secondary('Two Repository Setup')}`,
+                        `    Separate repository for documentation and planning.`,
+                        `    Best for: team projects, complex projects, when you want`,
+                        `    to keep planning separate from code.`,
+                        '',
+                        `  ${s.muted('Tip: Run /init in an empty directory to start fresh.')}`,
+                        '',
+                        `  After /init completes, the AI reads your COMPILR.md to understand`,
+                        `  your project context. You're ready for the next step: ${s.primary('/design')}`,
+                        '',
+                    ],
+                },
+            ],
+        },
+        // =========================================================================
+        // Topic 3: Design
+        // =========================================================================
+        {
+            id: 'design',
+            name: 'Design Your Project',
+            description: 'Requirements gathering',
+            pages: [
+                {
+                    title: '/design Command',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('/design')} is comprehensive requirements gathering through conversation.`,
+                        '',
+                        `  The AI guides you through three phases:`,
+                        '',
+                        `    ${s.primary('Phase 1: Vision & Goals')}`,
+                        `      - What problem are you solving?`,
+                        `      - Who is your target user?`,
+                        `      - What does success look like?`,
+                        '',
+                        `    ${s.primary('Phase 2: Features & Scope')}`,
+                        `      - What are the core features?`,
+                        `      - What's nice-to-have vs essential?`,
+                        `      - What's explicitly out of scope?`,
+                        '',
+                        `    ${s.primary('Phase 3: Technical Context')}`,
+                        `      - What constraints exist?`,
+                        `      - What integrations are needed?`,
+                        `      - What are your preferences?`,
+                        '',
+                    ],
+                },
+                {
+                    title: '/design - Output',
+                    lines: [
+                        '',
+                        `  ${s.secondary('What /design creates:')}`,
+                        '',
+                        `    ${s.success('+')} ${s.primary('Product Requirements Document (PRD)')}`,
+                        `       A comprehensive document capturing your vision,`,
+                        `       features, technical requirements, and constraints.`,
+                        '',
+                        `    ${s.success('+')} ${s.primary('5-15 Backlog Items')}`,
+                        `       Auto-generated from your requirements,`,
+                        `       ready to be built with /build.`,
+                        '',
+                        `    ${s.success('+')} ${s.primary('Clear Acceptance Criteria')}`,
+                        `       Each backlog item has defined done criteria`,
+                        `       so you know when it's complete.`,
+                        '',
+                        `  ${s.muted('Best for: serious projects that need thorough planning upfront.')}`,
+                        `  ${s.muted('Expect: 30+ minute conversation to capture everything.')}`,
+                        '',
+                    ],
+                },
+                {
+                    title: '/sketch Command',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('/sketch')} is a quick alternative to /design.`,
+                        '',
+                        `  Instead of a long conversation, it asks 6 simple questions:`,
+                        '',
+                        `    ${s.muted('1.')} What are you building?`,
+                        `    ${s.muted('2.')} Who is it for?`,
+                        `    ${s.muted('3.')} What are the 3-5 main features?`,
+                        `    ${s.muted('4.')} What tech stack?`,
+                        `    ${s.muted('5.')} Any constraints or requirements?`,
+                        `    ${s.muted('6.')} What's the MVP scope?`,
+                        '',
+                        `  ${s.secondary('Output:')} 3-8 backlog items, ready to build.`,
+                        '',
+                        `  ${s.muted('Best for: small projects, prototypes, or when you just')}`,
+                        `  ${s.muted('want to get started quickly without detailed planning.')}`,
+                        '',
+                    ],
+                },
+                {
+                    title: '/refine Command',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('/refine')} improves existing backlog items.`,
+                        '',
+                        `  ${s.secondary('Use it to:')}`,
+                        '',
+                        `    ${s.muted('+')} Break down large items into smaller, actionable tasks`,
+                        `    ${s.muted('+')} Add acceptance criteria to vague items`,
+                        `    ${s.muted('+')} Clarify ambiguous requirements`,
+                        `    ${s.muted('+')} Add technical details discovered during work`,
+                        '',
+                        `  ${s.secondary('Usage:')}`,
+                        `    ${s.primary('/refine')}           Let the AI suggest what to refine`,
+                        `    ${s.primary('/refine REQ-003')}   Refine a specific item`,
+                        '',
+                        `  ${s.muted('Best for: after initial design when you discover items')}`,
+                        `  ${s.muted('are too big or need more detail before building.')}`,
+                        '',
+                    ],
+                },
+                {
+                    title: '/arch Command',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('/arch')} creates architecture documentation.`,
+                        '',
+                        `  ${s.secondary('Document types you can create:')}`,
+                        '',
+                        `    ${s.muted('1.')} ${s.primary('ADR')} - Architecture Decision Record`,
+                        `        Document key technical decisions and their rationale`,
+                        '',
+                        `    ${s.muted('2.')} ${s.primary('System Diagram')} - Visual system overview`,
+                        `        Components, connections, data flow`,
+                        '',
+                        `    ${s.muted('3.')} ${s.primary('Data Model')} - Database/entity design`,
+                        `        Tables, relationships, constraints`,
+                        '',
+                        `    ${s.muted('4.')} ${s.primary('API Design')} - Endpoint documentation`,
+                        `        Routes, methods, request/response formats`,
+                        '',
+                        `    ${s.muted('5.')} ${s.primary('Component Overview')} - Module documentation`,
+                        `        How pieces fit together`,
+                        '',
+                    ],
+                },
+                {
+                    title: '/prd Command',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('/prd')} lets you update your Product Requirements Document.`,
+                        '',
+                        `  After /design creates your PRD, use /prd to amend it as`,
+                        `  your understanding evolves.`,
+                        '',
+                        `  ${s.secondary('Usage:')}`,
+                        `    ${s.primary('/prd')}           Interactive section selection`,
+                        `    ${s.primary('/prd vision')}    Update vision section directly`,
+                        `    ${s.primary('/prd scope')}     Update scope section directly`,
+                        `    ${s.primary('/prd features')}  Update features section directly`,
+                        '',
+                        `  ${s.secondary('Sections you can update:')}`,
+                        `    - Vision and goals`,
+                        `    - Features and scope`,
+                        `    - Technical context`,
+                        `    - Non-functional requirements`,
+                        '',
+                    ],
+                },
+            ],
+        },
+        // =========================================================================
+        // Topic 4: Backlog
+        // =========================================================================
+        {
+            id: 'backlog',
+            name: 'Manage Backlog',
+            description: 'Track and prioritize work',
+            pages: [
+                {
+                    title: '/backlog Command',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('/backlog')} opens an interactive overlay to manage your work items.`,
+                        '',
+                        `  ${s.secondary('Navigation:')}`,
+                        `    ${s.primary('↑/↓')}       Navigate through items`,
+                        `    ${s.primary('←/→')}       Navigate pages (if many items)`,
+                        `    ${s.primary('Tab')}       Switch filter (All, Feature, Bug, etc.)`,
+                        `    ${s.primary('/')}         Search items`,
+                        `    ${s.primary('Enter')}     View/edit item details`,
+                        '',
+                        `  ${s.secondary('Actions:')}`,
+                        `    ${s.primary('n')}         Create new item`,
+                        `    ${s.primary('Space')}     Toggle item status`,
+                        `    ${s.primary('p')}         Change priority`,
+                        `    ${s.primary('Esc')}       Close overlay`,
+                        '',
+                    ],
+                },
+                {
+                    title: '/backlog - Status Workflow',
+                    lines: [
+                        '',
+                        `  Items move through three statuses:`,
+                        '',
+                        `    ${s.warning('pending')}        Not started yet`,
+                        `         ${s.muted('↓')}`,
+                        `    ${s.primary('in-progress')}    Currently being worked on`,
+                        `         ${s.muted('↓')}`,
+                        `    ${s.success('done')}           Completed`,
+                        '',
+                        `  ${s.secondary('Item Types:')}`,
+                        `    ${s.muted('Feature')}      New functionality to build`,
+                        `    ${s.muted('Bug')}          Something broken to fix`,
+                        `    ${s.muted('Tech-Debt')}    Code improvements needed`,
+                        `    ${s.muted('Chore')}        Maintenance tasks`,
+                        '',
+                        `  Items are stored in ${s.primary('backlog.md')} and can also be edited manually.`,
+                        '',
+                    ],
+                },
+            ],
+        },
+        // =========================================================================
+        // Topic 5: Build
+        // =========================================================================
+        {
+            id: 'build',
+            name: 'Build',
+            description: 'Scaffold and implement',
+            pages: [
+                {
+                    title: '/scaffold Command',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('/scaffold')} creates your project's foundation structure.`,
+                        '',
+                        `  ${s.secondary('What it creates:')}`,
+                        '',
+                        `    ${s.success('+')} Directory structure (src/, tests/, etc.)`,
+                        `    ${s.success('+')} Configuration files (package.json, tsconfig, etc.)`,
+                        `    ${s.success('+')} Dependencies installation`,
+                        `    ${s.success('+')} Basic boilerplate code`,
+                        `    ${s.success('+')} Development scripts`,
+                        '',
+                        `  The agent reads your ${s.primary('COMPILR.md')} to understand your tech stack`,
+                        `  and creates an appropriate project structure.`,
+                        '',
+                        `  ${s.muted('When to use: before implementing features, when starting')}`,
+                        `  ${s.muted('from an empty project directory.')}`,
+                        '',
+                    ],
+                },
+                {
+                    title: '/build Command',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('/build')} implements backlog items.`,
+                        '',
+                        `  ${s.secondary('Usage:')}`,
+                        `    ${s.primary('/build')}           Pick the highest priority pending item`,
+                        `    ${s.primary('/build REQ-003')}   Build a specific item by ID`,
+                        `    ${s.primary('/build scaffold')}  Same as /scaffold`,
+                        '',
+                        `  ${s.secondary('The agent will:')}`,
+                        `    ${s.muted('1.')} Read and analyze the requirement`,
+                        `    ${s.muted('2.')} Plan the implementation approach`,
+                        `    ${s.muted('3.')} Write the code (with your approval)`,
+                        `    ${s.muted('4.')} Run tests if available`,
+                        `    ${s.muted('5.')} Update the backlog status to done`,
+                        '',
+                    ],
+                },
+                {
+                    title: '/build - Permissions',
+                    lines: [
+                        '',
+                        `  During /build, you'll see permission prompts for:`,
+                        '',
+                        `    ${s.warning('File changes')}`,
+                        `      The AI shows exactly what will be changed`,
+                        `      with a diff view before you approve.`,
+                        '',
+                        `    ${s.warning('Shell commands')}`,
+                        `      Commands like npm install or running tests`,
+                        `      require your explicit approval.`,
+                        '',
+                        `  ${s.secondary('Review carefully before approving!')}`,
+                        `  The AI shows exactly what will happen so you stay in control.`,
+                        '',
+                        `  ${s.muted('Tip: If /build detects an empty project, it will')}`,
+                        `  ${s.muted('suggest running /scaffold first.')}`,
+                        '',
+                    ],
+                },
+            ],
+        },
+        // =========================================================================
+        // Topic 6: Configuration
+        // =========================================================================
+        {
+            id: 'config',
+            name: 'Configuration',
+            description: 'Settings, keys, and themes',
+            pages: [
+                {
+                    title: '/config Command',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('/config')} opens the settings panel.`,
+                        '',
+                        `  ${s.secondary('Tabs:')}`,
+                        `    ${s.primary('Status')}    Version, model, session info`,
+                        `    ${s.primary('Config')}    Interactive settings`,
+                        `    ${s.primary('Usage')}     Token usage statistics`,
+                        '',
+                        `  ${s.secondary('Settings you can change:')}`,
+                        `    ${s.muted('Model')}         Switch AI model/provider`,
+                        `    ${s.muted('Theme')}         Choose from 400+ terminal themes`,
+                        `    ${s.muted('Permissions')}   Control approval prompts`,
+                        `    ${s.muted('Output')}        Verbose or minimal mode`,
+                        `    ${s.muted('Auto-compact')}  Automatic context management`,
+                        '',
+                    ],
+                },
+                {
+                    title: '/keys Command',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('/keys')} manages your API keys for LLM providers.`,
+                        '',
+                        `  ${s.secondary('Supported providers:')}`,
+                        `    ${s.primary('Claude')}    Anthropic's models (best reasoning)`,
+                        `    ${s.primary('OpenAI')}    GPT-4o and other models`,
+                        `    ${s.primary('Gemini')}    Google AI models`,
+                        `    ${s.primary('Ollama')}    Local models (no API key needed)`,
+                        '',
+                        `  Keys are encrypted and stored locally in:`,
+                        `  ${s.muted('~/.compilr-dev/credentials.enc')}`,
+                        '',
+                        `  ${s.muted('The CLI automatically opens /keys on first run')}`,
+                        `  ${s.muted('if no API key is configured.')}`,
+                        '',
+                    ],
+                },
+            ],
+        },
+        // =========================================================================
+        // Topic 7: Working with the Agent
+        // =========================================================================
+        {
+            id: 'agent',
+            name: 'Working with the Agent',
+            description: 'Chat, permissions, tips',
+            pages: [
+                {
+                    title: 'Chatting with the AI',
+                    lines: [
+                        '',
+                        `  Just type naturally. The AI understands context and can help with:`,
+                        '',
+                        `    ${s.muted('+')} Answering questions about your code`,
+                        `    ${s.muted('+')} Explaining how something works`,
+                        `    ${s.muted('+')} Writing new code or features`,
+                        `    ${s.muted('+')} Debugging issues`,
+                        `    ${s.muted('+')} Refactoring existing code`,
+                        `    ${s.muted('+')} Running commands and tests`,
+                        '',
+                        `  ${s.secondary('File References')}`,
+                        `    Type ${s.primary('@')} to autocomplete file paths.`,
+                        `    Example: ${s.muted('"Fix the bug in @src/utils.ts"')}`,
+                        '',
+                        `  The AI will read the file and understand the context.`,
+                        '',
+                    ],
+                },
+                {
+                    title: 'Permissions',
+                    lines: [
+                        '',
+                        `  The agent asks permission before:`,
+                        '',
+                        `    ${s.warning('+')} Modifying or creating files`,
+                        `    ${s.warning('+')} Running shell commands`,
+                        `    ${s.warning('+')} Making git commits`,
+                        '',
+                        `  ${s.secondary('For each action, you can:')}`,
+                        `    ${s.primary('Allow')}          Approve this specific action`,
+                        `    ${s.primary('Allow Always')}   Auto-approve this tool for the session`,
+                        `    ${s.primary('Deny')}           Reject this action`,
+                        '',
+                        `  For file edits, you'll see a diff showing exactly what changes.`,
+                        `  Review carefully - you're always in control.`,
+                        '',
+                    ],
+                },
+                {
+                    title: 'Suggestions',
+                    lines: [
+                        '',
+                        `  After completing tasks, the AI suggests next actions.`,
+                        '',
+                        `  ${s.secondary('How it works:')}`,
+                        `    Suggestions appear as ${s.muted('ghost text')} in your input prompt.`,
+                        `    Press ${s.primary('Tab')} to accept the suggestion.`,
+                        `    Or just keep typing to ignore it.`,
+                        '',
+                        `  ${s.secondary('Common suggestions:')}`,
+                        `    ${s.muted('"run the tests"')}`,
+                        `    ${s.muted('"commit the changes"')}`,
+                        `    ${s.muted('"build the next item"')}`,
+                        '',
+                        `  Suggestions help maintain workflow momentum.`,
+                        '',
+                    ],
+                },
+                {
+                    title: 'Context Management',
+                    lines: [
+                        '',
+                        `  The AI has a limited context window. When it fills up:`,
+                        '',
+                        `  ${s.primaryBold('/compact')}`,
+                        `    Summarizes old messages to free up space.`,
+                        `    The AI creates a summary and removes old messages.`,
+                        '',
+                        `  ${s.primaryBold('/context')}`,
+                        `    Shows current context usage (tokens used / available).`,
+                        '',
+                        `  ${s.primaryBold('/tokens')}`,
+                        `    Shows token usage statistics for the session.`,
+                        '',
+                        `  ${s.muted('Tip: Auto-compact is enabled by default in settings.')}`,
+                        `  ${s.muted('The AI will automatically summarize when needed.')}`,
+                        '',
+                    ],
+                },
+            ],
+        },
+        // =========================================================================
+        // Topic 8: Tips & Tricks
+        // =========================================================================
+        {
+            id: 'tips',
+            name: 'Tips & Tricks',
+            description: 'Shortcuts and best practices',
+            pages: [
+                {
+                    title: 'Keyboard Shortcuts',
+                    lines: [
+                        '',
+                        `  ${s.secondary('Input:')}`,
+                        `    ${s.primary('Tab')}          Accept suggestion or autocomplete`,
+                        `    ${s.primary('Esc')}          Cancel current operation`,
+                        `    ${s.primary('Ctrl+C')}       Stop the agent or exit`,
+                        '',
+                        `  ${s.secondary('In Overlays:')}`,
+                        `    ${s.primary('↑/↓')}          Navigate options`,
+                        `    ${s.primary('←/→')}          Navigate pages or tabs`,
+                        `    ${s.primary('Tab')}          Switch tabs (where applicable)`,
+                        `    ${s.primary('Enter')}        Confirm selection`,
+                        `    ${s.primary('Esc')}          Go back or close`,
+                        '',
+                        `  ${s.secondary('Special:')}`,
+                        `    ${s.primary('@')}            Start file autocomplete`,
+                        `    ${s.primary('/')}            Start command autocomplete`,
+                        '',
+                    ],
+                },
+                {
+                    title: 'Useful Commands',
+                    lines: [
+                        '',
+                        `  ${s.secondary('Information:')}`,
+                        `    ${s.primary('/help')}        Full command reference`,
+                        `    ${s.primary('/status')}      Version, model, mode info`,
+                        `    ${s.primary('/tools')}       List available tools`,
+                        '',
+                        `  ${s.secondary('Session:')}`,
+                        `    ${s.primary('/note')}        Create session documentation`,
+                        `    ${s.primary('/export')}      Export conversation`,
+                        `    ${s.primary('/clear')}       Clear the screen`,
+                        '',
+                        `  ${s.secondary('Mode:')}`,
+                        `    ${s.primary('/plan')}        Switch to planning mode`,
+                        `                  (focus on design, not implementation)`,
+                        '',
+                    ],
+                },
+                {
+                    title: 'Best Practices',
+                    lines: [
+                        '',
+                        `  ${s.primary('1.')} Start with ${s.primaryBold('/init')}, then ${s.primaryBold('/design')} or ${s.primaryBold('/sketch')}`,
+                        `     Don't skip planning - it pays off later.`,
+                        '',
+                        `  ${s.primary('2.')} Keep backlog items small and focused`,
+                        `     Break large features into smaller tasks.`,
+                        '',
+                        `  ${s.primary('3.')} Review AI suggestions before approving`,
+                        `     You're in control - understand what's changing.`,
+                        '',
+                        `  ${s.primary('4.')} Use ${s.primaryBold('/arch')} to document key decisions`,
+                        `     Future you will thank present you.`,
+                        '',
+                        `  ${s.primary('5.')} Try ${s.primaryBold('Ollama')} for offline development`,
+                        `     No API key needed, runs locally.`,
+                        '',
+                    ],
+                },
+            ],
+        },
+    ];
+}
+// =============================================================================
+// Rendering
+// =============================================================================
+function renderWelcome(state, previousLineCount) {
+    const s = getStyles();
+    const lines = [];
+    const border = getBorder();
+    if (previousLineCount > 0) {
+        terminal.clearLinesAbove(previousLineCount);
+    }
+    lines.push(border);
+    lines.push(` ${s.primaryBold('compilr.dev Tutorial')}`);
+    lines.push('');
+    lines.push(`  Learn the AI-powered development workflow that takes you`);
+    lines.push(`  from idea to implementation with structure and discipline.`);
+    lines.push('');
+    lines.push(`  This tutorial covers: initialization, design, backlog`);
+    lines.push(`  management, building, configuration, and best practices.`);
+    lines.push('');
+    lines.push(`  ${s.muted('How would you like to explore?')}`);
+    lines.push('');
+    const options = [
+        { label: 'Start Guided Tour', desc: 'Step-by-step walkthrough (recommended)' },
+        { label: 'Jump to Topic', desc: 'Go directly to a specific topic' },
+    ];
+    for (let i = 0; i < options.length; i++) {
+        const opt = options[i];
+        const selected = i === state.welcomeIndex;
+        const prefix = selected ? s.primary(' ❯ ') : '   ';
+        const label = selected ? s.primary(opt.label) : opt.label;
+        const desc = s.muted(opt.desc);
+        lines.push(`${prefix}${label.padEnd(22)} ${desc}`);
+    }
+    lines.push('');
+    lines.push(border);
+    lines.push(s.muted(' ↑↓ Navigate · Enter Select · Esc Exit'));
+    terminal.write(lines.join('\n'));
+    return lines.length;
+}
+function renderTopicList(state, topics, previousLineCount) {
+    const s = getStyles();
+    const lines = [];
+    const border = getBorder();
+    if (previousLineCount > 0) {
+        terminal.clearLinesAbove(previousLineCount);
+    }
+    lines.push(border);
+    lines.push(` ${s.primaryBold('Tutorial Topics')}`);
+    lines.push('');
+    for (let i = 0; i < topics.length; i++) {
+        const topic = topics[i];
+        const selected = i === state.topicListIndex;
+        const prefix = selected ? s.primary(' ❯ ') : '   ';
+        const name = selected ? s.primary(topic.name) : topic.name;
+        const desc = s.muted(topic.description);
+        const pages = s.muted(`(${String(topic.pages.length)} ${topic.pages.length === 1 ? 'page' : 'pages'})`);
+        lines.push(`${prefix}${name.padEnd(26)} ${desc.padEnd(30)} ${pages}`);
+    }
+    lines.push('');
+    lines.push(border);
+    lines.push(s.muted(' ↑↓ Navigate · Enter View · Esc Back'));
+    terminal.write(lines.join('\n'));
+    return lines.length;
+}
+function renderPage(state, topics, previousLineCount) {
+    const s = getStyles();
+    const lines = [];
+    const border = getBorder();
+    if (previousLineCount > 0) {
+        terminal.clearLinesAbove(previousLineCount);
+    }
+    const topic = topics[state.currentTopicIndex];
+    const page = topic.pages[state.currentPageIndex];
+    const totalPages = topic.pages.length;
+    // Calculate overall progress for guided mode
+    let progressText = `[${String(state.currentPageIndex + 1)}/${String(totalPages)}]`;
+    if (state.isGuidedMode) {
+        let totalPagesAll = 0;
+        let currentPageAll = 0;
+        for (let i = 0; i < topics.length; i++) {
+            if (i < state.currentTopicIndex) {
+                currentPageAll += topics[i].pages.length;
+            }
+            else if (i === state.currentTopicIndex) {
+                currentPageAll += state.currentPageIndex + 1;
+            }
+            totalPagesAll += topics[i].pages.length;
+        }
+        progressText = `[${String(currentPageAll)}/${String(totalPagesAll)}]`;
+    }
+    // Header - calculate padding to right-align progress indicator
+    const titleStyled = s.primaryBold(page.title);
+    const progressStyled = s.muted(progressText);
+    const titleLen = stripAnsi(titleStyled).length + 1; // +1 for leading space
+    const progressLen = stripAnsi(progressStyled).length;
+    const cols = terminal.getTerminalWidth();
+    const padding = Math.max(1, cols - titleLen - progressLen - 2); // -2 for margins
+    lines.push(border);
+    lines.push(` ${titleStyled}${' '.repeat(padding)}${progressStyled}`);
+    lines.push('');
+    // Content
+    for (const line of page.lines) {
+        lines.push(line);
+    }
+    // Pad to consistent height
+    while (lines.length < 20) {
+        lines.push('');
+    }
+    // Navigation footer
+    lines.push(border);
+    if (state.isGuidedMode) {
+        lines.push(s.muted(' ←/→ Navigate · Esc Exit Tour'));
+    }
+    else {
+        lines.push(s.muted(' ←/→ Navigate · Esc Back to Topics'));
+    }
+    terminal.write(lines.join('\n'));
+    return lines.length;
+}
+function renderComplete(previousLineCount) {
+    const s = getStyles();
+    const lines = [];
+    const border = getBorder();
+    if (previousLineCount > 0) {
+        terminal.clearLinesAbove(previousLineCount);
+    }
+    lines.push(border);
+    lines.push(` ${s.success('Tutorial Complete!')}`);
+    lines.push('');
+    lines.push(`  You've learned the compilr.dev workflow!`);
+    lines.push('');
+    lines.push(`  ${s.secondary('Key commands to remember:')}`);
+    lines.push('');
+    lines.push(`    ${s.primary('/init')}       Start a new project`);
+    lines.push(`    ${s.primary('/design')}     Plan your requirements`);
+    lines.push(`    ${s.primary('/backlog')}    Manage your work items`);
+    lines.push(`    ${s.primary('/build')}      Implement features`);
+    lines.push(`    ${s.primary('/help')}       See all commands`);
+    lines.push('');
+    lines.push(`  ${s.secondary('Ready to start?')}`);
+    lines.push(`  Try ${s.primary('/init')} in a new directory!`);
+    lines.push('');
+    lines.push(border);
+    lines.push(s.muted(' Press any key to exit...'));
+    terminal.write(lines.join('\n'));
+    return lines.length;
+}
+function render(state, topics, previousLineCount) {
+    switch (state.mode) {
+        case 'welcome':
+            return renderWelcome(state, previousLineCount);
+        case 'topic-list':
+            return renderTopicList(state, topics, previousLineCount);
+        case 'viewing':
+            return renderPage(state, topics, previousLineCount);
+        case 'complete':
+            return renderComplete(previousLineCount);
+    }
+}
+// =============================================================================
+// Main Export
+// =============================================================================
+export async function showTutorialOverlay() {
+    const topics = buildTopics();
+    const state = {
+        mode: 'welcome',
+        welcomeIndex: 0,
+        topicListIndex: 0,
+        currentTopicIndex: 0,
+        currentPageIndex: 0,
+        isGuidedMode: false,
+    };
+    let lineCount = 0;
+    lineCount = render(state, topics, lineCount);
+    return new Promise((resolve) => {
+        const stdin = process.stdin;
+        stdin.setRawMode(true);
+        stdin.resume();
+        const cleanup = () => {
+            stdin.removeListener('data', handleKey);
+            stdin.setRawMode(false);
+            stdin.pause();
+            terminal.clearLinesAbove(lineCount);
+        };
+        const handleKey = (data) => {
+            const key = data.toString();
+            const isEscape = key === '\x1B' && data.length === 1;
+            const isEnter = key === '\r' || key === '\n';
+            const isUpArrow = key === '\x1B[A';
+            const isDownArrow = key === '\x1B[B';
+            const isLeftArrow = key === '\x1B[D';
+            const isRightArrow = key === '\x1B[C';
+            const isCtrlC = key === '\x03';
+            if (isCtrlC) {
+                cleanup();
+                resolve({ completed: false });
+                return;
+            }
+            switch (state.mode) {
+                case 'welcome': {
+                    if (isEscape) {
+                        cleanup();
+                        resolve({ completed: false });
+                        return;
+                    }
+                    if (isUpArrow && state.welcomeIndex > 0) {
+                        state.welcomeIndex--;
+                    }
+                    else if (isDownArrow && state.welcomeIndex < 1) {
+                        state.welcomeIndex++;
+                    }
+                    else if (isEnter) {
+                        if (state.welcomeIndex === 0) {
+                            state.isGuidedMode = true;
+                            state.currentTopicIndex = 0;
+                            state.currentPageIndex = 0;
+                            state.mode = 'viewing';
+                        }
+                        else {
+                            state.mode = 'topic-list';
+                        }
+                    }
+                    break;
+                }
+                case 'topic-list': {
+                    if (isEscape) {
+                        state.mode = 'welcome';
+                    }
+                    else if (isUpArrow && state.topicListIndex > 0) {
+                        state.topicListIndex--;
+                    }
+                    else if (isDownArrow && state.topicListIndex < topics.length - 1) {
+                        state.topicListIndex++;
+                    }
+                    else if (isEnter) {
+                        state.isGuidedMode = false;
+                        state.currentTopicIndex = state.topicListIndex;
+                        state.currentPageIndex = 0;
+                        state.mode = 'viewing';
+                    }
+                    break;
+                }
+                case 'viewing': {
+                    const topic = topics[state.currentTopicIndex];
+                    const totalPages = topic.pages.length;
+                    if (isEscape) {
+                        if (state.isGuidedMode) {
+                            state.mode = 'welcome';
+                        }
+                        else {
+                            state.mode = 'topic-list';
+                        }
+                    }
+                    else if (isLeftArrow || key === '\x7F') {
+                        if (state.currentPageIndex > 0) {
+                            state.currentPageIndex--;
+                        }
+                        else if (state.isGuidedMode && state.currentTopicIndex > 0) {
+                            state.currentTopicIndex--;
+                            state.currentPageIndex = topics[state.currentTopicIndex].pages.length - 1;
+                        }
+                    }
+                    else if (isRightArrow || isEnter) {
+                        if (state.currentPageIndex < totalPages - 1) {
+                            state.currentPageIndex++;
+                        }
+                        else if (state.isGuidedMode) {
+                            if (state.currentTopicIndex < topics.length - 1) {
+                                state.currentTopicIndex++;
+                                state.currentPageIndex = 0;
+                            }
+                            else {
+                                state.mode = 'complete';
+                            }
+                        }
+                    }
+                    break;
+                }
+                case 'complete': {
+                    cleanup();
+                    resolve({ completed: true });
+                    return;
+                }
+            }
+            lineCount = render(state, topics, lineCount);
+        };
+        stdin.on('data', handleKey);
+    });
+}