@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/ui/overlay/impl/tutorial-overlay-v2.js

@@ -0,0 +1,1035 @@
+/**
+ * Tutorial Overlay V2
+ *
+ * Interactive tutorial using the new Overlay interface.
+ * Supports guided sequential tour and topic-based navigation.
+ */
+import { BaseOverlayV2, BaseScreen, ScreenStack, stay, pushScreen, popScreen, closeOverlay, isEscape, isEnter, isCtrlC, isClose, isNavigateUp, isNavigateDown, isLeftArrow, isRightArrow, isVimLeft, isVimRight, isBackspace, renderBorder, } from '../../base/index.js';
+// =============================================================================
+// Helper
+// =============================================================================
+function stripAnsi(str) {
+    // eslint-disable-next-line no-control-regex
+    return str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');
+}
+// =============================================================================
+// Content
+// =============================================================================
+function buildTopics(s) {
+    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('/new')}      Set up your project structure`,
+                        `               Creates project in database with configuration`,
+                        '',
+                        `    ${s.primary('/design')}    Gather requirements and create a PRD`,
+                        `               Documents stored in database for persistence`,
+                        '',
+                        `    ${s.primary('/backlog')}   Manage your work items`,
+                        `               Track status, prioritize, break down tasks`,
+                        '',
+                        `    ${s.primary('/build')}     Implement features from the backlog`,
+                        `               AI-assisted coding with your approval`,
+                        '',
+                        `    ${s.primary('/workflow')}  Check progress and next steps`,
+                        `               See where you are and what's next`,
+                        '',
+                    ],
+                },
+                {
+                    title: 'Project Management',
+                    lines: [
+                        '',
+                        `  ${s.secondary('Track Your Progress')}`,
+                        '',
+                        `  ${s.primaryBold('/projects')}`,
+                        `    View all your projects in one place.`,
+                        `    Filter by status: Active, Paused, Completed, Archived.`,
+                        `    Switch between projects or open project directories.`,
+                        '',
+                        `  ${s.primaryBold('/workflow')}`,
+                        `    See your current project's workflow status.`,
+                        `    Shows which phases are complete and what's next.`,
+                        `    Quick actions to jump to the right command.`,
+                        '',
+                        `  ${s.primaryBold('/docs')}`,
+                        `    Browse documents created during design.`,
+                        `    View PRDs, architecture docs, and notes.`,
+                        '',
+                    ],
+                },
+            ],
+        },
+        // =========================================================================
+        // Topic 2: Initialize
+        // =========================================================================
+        {
+            id: 'init',
+            name: 'Initialize',
+            description: 'Setting up a new project',
+            pages: [
+                {
+                    title: '/new Command',
+                    lines: [
+                        '',
+                        `  ${s.primaryBold('/new')} creates your project foundation through an 8-step wizard.`,
+                        '',
+                        `  ${s.secondary('What it creates:')}`,
+                        '',
+                        `    ${s.success('+')} ${s.primary('Project in database')} - Tracked for easy management`,
+                        `    ${s.success('+')} ${s.primary('COMPILR.md')} - Context file for the AI assistant`,
+                        `    ${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`,
+                        `    - Workflow mode (flexible or guided)`,
+                        '',
+                    ],
+                },
+                {
+                    title: '/new - Database Tracking',
+                    lines: [
+                        '',
+                        `  ${s.secondary('Project Database')}`,
+                        `    All projects are tracked in a local SQLite database.`,
+                        `    This enables: multi-project switching, progress tracking,`,
+                        `    and persistent work item management.`,
+                        '',
+                        `  ${s.secondary('View Your Projects')}`,
+                        `    Use ${s.primary('/projects')} to see all your projects.`,
+                        `    Use ${s.primary('/workflow')} to see current project status.`,
+                        '',
+                        `  ${s.muted('Tip: Run /new in an empty directory to start fresh.')}`,
+                        '',
+                        `  After /new 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)')}`,
+                        `       Stored in the database for persistence.`,
+                        `       Use ${s.primary('/docs')} to view it anytime.`,
+                        '',
+                        `    ${s.success('+')} ${s.primary('5-15 Backlog Items')}`,
+                        `       Stored in database with status tracking.`,
+                        `       Use ${s.primary('/backlog')} to manage them.`,
+                        '',
+                        `    ${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.')}`,
+                        '',
+                    ],
+                },
+                {
+                    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('backlog')}       Not started yet`,
+                        `         ${s.muted('↓')}`,
+                        `    ${s.primary('in-progress')}    Currently being worked on`,
+                        `         ${s.muted('↓')}`,
+                        `    ${s.success('completed')}      Done!`,
+                        '',
+                        `  ${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 the ${s.primary('database')} and persist across sessions.`,
+                        '',
+                    ],
+                },
+            ],
+        },
+        // =========================================================================
+        // 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.')}`,
+                        '',
+                    ],
+                },
+                {
+                    title: 'Anchors - Persistent Context',
+                    lines: [
+                        '',
+                        `  ${s.secondary('Anchors')} are critical pieces of information that survive`,
+                        `  context compaction. They're always included at the top of context.`,
+                        '',
+                        `  ${s.primaryBold('/anchors')}`,
+                        `    View and manage your anchors.`,
+                        `    Add, edit, or remove persistent context.`,
+                        '',
+                        `  ${s.secondary('When to use anchors:')}`,
+                        `    ${s.muted('+')} Project context that must never be forgotten`,
+                        `    ${s.muted('+')} Key architectural decisions`,
+                        `    ${s.muted('+')} User preferences for code style`,
+                        `    ${s.muted('+')} Important constraints or requirements`,
+                        '',
+                        `  ${s.secondary('Scope:')}`,
+                        `    ${s.primary('Global')}   - Persists across all projects`,
+                        `    ${s.primary('Project')}  - Specific to current project`,
+                        '',
+                    ],
+                },
+            ],
+        },
+        // =========================================================================
+        // 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('/new')}, 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.`,
+                        '',
+                    ],
+                },
+            ],
+        },
+    ];
+}
+// =============================================================================
+// Screens
+// =============================================================================
+/**
+ * Welcome screen - shows entry options (guided tour or topic list)
+ */
+class WelcomeScreen extends BaseScreen {
+    state;
+    styles;
+    topics;
+    getWidth;
+    selectedIndex = 0;
+    constructor(state, styles, topics, getWidth) {
+        super();
+        this.state = state;
+        this.styles = styles;
+        this.topics = topics;
+        this.getWidth = getWidth;
+    }
+    render() {
+        const s = this.styles;
+        const cols = this.getWidth();
+        const border = renderBorder(cols, s);
+        const lines = [];
+        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 === this.selectedIndex;
+            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(' ↑↓/jk Navigate · Enter Select · q/Esc Exit'));
+        return lines;
+    }
+    handleKey(data) {
+        // Close keys
+        if (isCtrlC(data) || isClose(data)) {
+            return closeOverlay({ completed: false });
+        }
+        // Navigation
+        if (isNavigateUp(data) && this.selectedIndex > 0) {
+            this.selectedIndex--;
+            return stay();
+        }
+        if (isNavigateDown(data) && this.selectedIndex < 1) {
+            this.selectedIndex++;
+            return stay();
+        }
+        // Enter - select option
+        if (isEnter(data)) {
+            if (this.selectedIndex === 0) {
+                // Guided mode
+                this.state.isGuidedMode = true;
+                this.state.currentTopicIndex = 0;
+                this.state.currentPageIndex = 0;
+                return pushScreen(new ViewingScreen(this.state, this.styles, this.topics, this.getWidth));
+            }
+            else {
+                // Topic list mode
+                return pushScreen(new TopicListScreen(this.state, this.styles, this.topics, this.getWidth));
+            }
+        }
+        return stay(false);
+    }
+}
+/**
+ * Topic list screen - shows all topics to choose from
+ */
+class TopicListScreen extends BaseScreen {
+    state;
+    styles;
+    topics;
+    getWidth;
+    constructor(state, styles, topics, getWidth) {
+        super();
+        this.state = state;
+        this.styles = styles;
+        this.topics = topics;
+        this.getWidth = getWidth;
+    }
+    render() {
+        const s = this.styles;
+        const cols = this.getWidth();
+        const border = renderBorder(cols, s);
+        const lines = [];
+        lines.push(border);
+        lines.push(` ${s.primaryBold('Tutorial Topics')}`);
+        lines.push('');
+        for (let i = 0; i < this.topics.length; i++) {
+            const topic = this.topics[i];
+            const selected = i === this.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(' ↑↓/jk Navigate · Enter View · q/Esc Close'));
+        return lines;
+    }
+    handleKey(data) {
+        // Ctrl+C or q closes overlay
+        if (isCtrlC(data)) {
+            return closeOverlay({ completed: false });
+        }
+        // Escape goes back to welcome
+        if (isEscape(data)) {
+            return popScreen();
+        }
+        // Navigation
+        if (isNavigateUp(data) && this.state.topicListIndex > 0) {
+            this.state.topicListIndex--;
+            return stay();
+        }
+        if (isNavigateDown(data) && this.state.topicListIndex < this.topics.length - 1) {
+            this.state.topicListIndex++;
+            return stay();
+        }
+        // Enter - view topic
+        if (isEnter(data)) {
+            this.state.isGuidedMode = false;
+            this.state.currentTopicIndex = this.state.topicListIndex;
+            this.state.currentPageIndex = 0;
+            return pushScreen(new ViewingScreen(this.state, this.styles, this.topics, this.getWidth));
+        }
+        return stay(false);
+    }
+}
+/**
+ * Viewing screen - shows a page from a topic with navigation
+ */
+class ViewingScreen extends BaseScreen {
+    state;
+    styles;
+    topics;
+    getWidth;
+    constructor(state, styles, topics, getWidth) {
+        super();
+        this.state = state;
+        this.styles = styles;
+        this.topics = topics;
+        this.getWidth = getWidth;
+    }
+    render() {
+        const s = this.styles;
+        const cols = this.getWidth();
+        const border = renderBorder(cols, s);
+        const lines = [];
+        const topic = this.topics[this.state.currentTopicIndex];
+        const page = topic.pages[this.state.currentPageIndex];
+        const totalPages = topic.pages.length;
+        // Calculate overall progress for guided mode
+        let progressText = `[${String(this.state.currentPageIndex + 1)}/${String(totalPages)}]`;
+        if (this.state.isGuidedMode) {
+            let totalPagesAll = 0;
+            let currentPageAll = 0;
+            for (let i = 0; i < this.topics.length; i++) {
+                if (i < this.state.currentTopicIndex) {
+                    currentPageAll += this.topics[i].pages.length;
+                }
+                else if (i === this.state.currentTopicIndex) {
+                    currentPageAll += this.state.currentPageIndex + 1;
+                }
+                totalPagesAll += this.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 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 (this.state.isGuidedMode) {
+            lines.push(s.muted(' ←/→/hl Navigate · Esc Exit Tour'));
+        }
+        else {
+            lines.push(s.muted(' ←/→/hl Navigate · Esc Back to Topics'));
+        }
+        return lines;
+    }
+    handleKey(data) {
+        // Ctrl+C closes overlay
+        if (isCtrlC(data)) {
+            return closeOverlay({ completed: false });
+        }
+        const topic = this.topics[this.state.currentTopicIndex];
+        const totalPages = topic.pages.length;
+        // Escape goes back
+        if (isEscape(data)) {
+            return popScreen();
+        }
+        // Previous page (left arrow, h, or backspace)
+        if (isLeftArrow(data) || isVimLeft(data) || isBackspace(data)) {
+            if (this.state.currentPageIndex > 0) {
+                this.state.currentPageIndex--;
+                return stay();
+            }
+            else if (this.state.isGuidedMode && this.state.currentTopicIndex > 0) {
+                this.state.currentTopicIndex--;
+                this.state.currentPageIndex = this.topics[this.state.currentTopicIndex].pages.length - 1;
+                return stay();
+            }
+            return stay(false);
+        }
+        // Next page (right arrow, l, or enter)
+        if (isRightArrow(data) || isVimRight(data) || isEnter(data)) {
+            if (this.state.currentPageIndex < totalPages - 1) {
+                this.state.currentPageIndex++;
+                return stay();
+            }
+            else if (this.state.isGuidedMode) {
+                if (this.state.currentTopicIndex < this.topics.length - 1) {
+                    this.state.currentTopicIndex++;
+                    this.state.currentPageIndex = 0;
+                    return stay();
+                }
+                else {
+                    // End of guided tour - show complete screen
+                    return pushScreen(new CompleteScreen(this.styles, this.getWidth));
+                }
+            }
+            return stay(false);
+        }
+        return stay(false);
+    }
+}
+/**
+ * Complete screen - shows completion message
+ */
+class CompleteScreen extends BaseScreen {
+    styles;
+    getWidth;
+    constructor(styles, getWidth) {
+        super();
+        this.styles = styles;
+        this.getWidth = getWidth;
+    }
+    render() {
+        const s = this.styles;
+        const cols = this.getWidth();
+        const border = renderBorder(cols, s);
+        const lines = [];
+        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('/new')}       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('/new')} in a new directory!`);
+        lines.push('');
+        lines.push(border);
+        lines.push(s.muted(' Press any key to exit...'));
+        return lines;
+    }
+    handleKey(_data) {
+        // Any key closes the overlay with completed = true
+        return closeOverlay({ completed: true });
+    }
+}
+// =============================================================================
+// Tutorial Overlay V2 Class
+// =============================================================================
+/**
+ * Tutorial overlay using the new Overlay interface.
+ * Multi-screen overlay for interactive tutorial.
+ */
+export class TutorialOverlayV2 extends BaseOverlayV2 {
+    type = 'inline';
+    id = 'tutorial-overlay-v2';
+    screenStack;
+    topics = [];
+    constructor() {
+        const initialState = {
+            topicListIndex: 0,
+            currentTopicIndex: 0,
+            currentPageIndex: 0,
+            isGuidedMode: false,
+        };
+        super(initialState);
+        this.minHeight = 24;
+        this.screenStack = new ScreenStack();
+        // Topics will be built on first render when we have styles
+    }
+    renderContent(context) {
+        // Build topics on first render (needs styles)
+        if (this.topics.length === 0) {
+            this.topics = buildTopics(context.styles);
+            this.screenStack.push(new WelcomeScreen(this.state, context.styles, this.topics, () => this.termWidth));
+        }
+        const screen = this.screenStack.current();
+        return screen?.render() ?? [];
+    }
+    handleKey(key) {
+        const data = key.raw;
+        const screen = this.screenStack.current();
+        if (!screen) {
+            return this.close({ completed: false });
+        }
+        const result = screen.handleKey(data);
+        switch (result.action) {
+            case 'stay':
+                return result.render ? this.rerender() : this.noAction();
+            case 'push':
+                this.screenStack.push(result.screen);
+                return this.rerender();
+            case 'pop':
+                this.screenStack.pop();
+                return this.rerender();
+            case 'close':
+                return this.close(result.result);
+        }
+    }
+}