@compilr-dev/cli 0.5.0 → 0.5.2

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

@@ -1,10 +1,20 @@
 /**
  * Tutorial Overlay V2
  *
- * Interactive tutorial using the new Overlay interface.
- * Supports guided sequential tour and topic-based navigation.
+ * Interactive tutorial with guided walkthroughs.
+ * Extends TabbedListOverlayV2 for consistent UI with other overlays.
+ *
+ * Features:
+ * - 5 tabs: Basics, Projects, Planning, Teams, Config
+ * - Searchable tutorial list
+ * - Multi-page detail view for each tutorial
  */
-import { BaseOverlayV2, BaseScreen, ScreenStack, stay, pushScreen, popScreen, closeOverlay, isEscape, isEnter, isCtrlC, isClose, isNavigateUp, isNavigateDown, isLeftArrow, isRightArrow, isVimLeft, isVimRight, isBackspace, renderBorder, } from '../../base/index.js';
+import { TabbedListOverlayV2, BaseScreen, stay, popScreen, closeOverlay, isEscape, isEnter, isCtrlC, isQuit, isLeftArrow, isRightArrow, isVimLeft, isVimRight, isBackspace, renderBorder, } from '../../base/index.js';
+import { buildTutorialContent, } from '../data/tutorial-content.js';
+// =============================================================================
+// Constants
+// =============================================================================
+const PAGE_SIZE = 8;
 // =============================================================================
 // Helper
 // =============================================================================
@@ -13,864 +23,41 @@ function stripAnsi(str) {
     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
+// Viewing Screen (Multi-page Tutorial Content)
 // =============================================================================
 /**
- * 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
+ * Shows a page from a tutorial with navigation.
+ * Allows navigating through multiple pages with ←/→.
  */
 class ViewingScreen extends BaseScreen {
-    state;
+    item;
     styles;
-    topics;
     getWidth;
-    constructor(state, styles, topics, getWidth) {
+    currentPageIndex = 0;
+    constructor(item, styles, getWidth) {
         super();
-        this.state = state;
+        this.item = item;
         this.styles = styles;
-        this.topics = topics;
         this.getWidth = getWidth;
     }
+    getMinHeight() {
+        return 24;
+    }
     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 page = this.item.pages[this.currentPageIndex];
+        const totalPages = this.item.pages.length;
+        // Progress text
+        const progressText = `[${String(this.currentPageIndex + 1)}/${String(totalPages)}]`;
+        // Header with progress
         const titleStyled = s.primaryBold(page.title);
         const progressStyled = s.muted(progressText);
-        const titleLen = stripAnsi(titleStyled).length + 1; // +1 for leading space
+        const titleLen = stripAnsi(titleStyled).length + 1;
         const progressLen = stripAnsi(progressStyled).length;
-        const padding = Math.max(1, cols - titleLen - progressLen - 2); // -2 for margins
+        const padding = Math.max(1, cols - titleLen - progressLen - 2);
         lines.push(border);
         lines.push(` ${titleStyled}${' '.repeat(padding)}${progressStyled}`);
         lines.push('');
@@ -884,152 +71,142 @@ class ViewingScreen extends BaseScreen {
         }
         // 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'));
+        // Show appropriate hints based on position
+        const hints = [];
+        if (this.currentPageIndex > 0 || totalPages > 1) {
+            hints.push('←/→ navigate');
         }
+        hints.push('q/Esc back');
+        lines.push(s.muted(`  ${hints.join(' · ')}`));
         return lines;
     }
     handleKey(data) {
-        // Ctrl+C closes overlay
+        // Ctrl+C closes overlay completely
         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)) {
+        const totalPages = this.item.pages.length;
+        // Back to topic list
+        if (isEscape(data) || isQuit(data)) {
             return popScreen();
         }
-        // Previous page (left arrow, h, or backspace)
+        // Previous page
         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;
+            if (this.currentPageIndex > 0) {
+                this.currentPageIndex--;
                 return stay();
             }
             return stay(false);
         }
-        // Next page (right arrow, l, or enter)
+        // Next page
         if (isRightArrow(data) || isVimRight(data) || isEnter(data)) {
-            if (this.state.currentPageIndex < totalPages - 1) {
-                this.state.currentPageIndex++;
+            if (this.currentPageIndex < totalPages - 1) {
+                this.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));
-                }
+            // At last page, Enter goes back to list
+            if (isEnter(data)) {
+                return popScreen();
             }
             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.
+ * Tutorial overlay with tabbed topics and multi-page walkthroughs.
+ * Extends TabbedListOverlayV2 for consistent look with other overlays.
  */
-export class TutorialOverlayV2 extends BaseOverlayV2 {
+export class TutorialOverlayV2 extends TabbedListOverlayV2 {
     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
+        // We need styles to build content, but we don't have them yet.
+        // Build with a placeholder and rebuild on first render.
+        // For now, use empty items - they'll be populated on first render.
+        const tabs = [
+            { id: 'basics', label: 'Basics' },
+            { id: 'projects', label: 'Projects' },
+            { id: 'plan-build', label: 'Plan & Build' },
+            { id: 'teams', label: 'Teams' },
+            { id: 'config', label: 'Config' },
+        ];
+        super({
+            title: 'Tutorial',
+            tabs,
+            items: [], // Will be populated on first render
+            pageSize: PAGE_SIZE,
+            filterByTab: (item, tabId) => {
+                if (tabId === 'all')
+                    return true;
+                return item.tabId === tabId;
+            },
+            getSearchText: (item) => `${item.title} ${item.description}`,
+            renderItem: (item, isSelected, styles) => {
+                const prefix = isSelected ? styles.primary(' ► ') : '   ';
+                // Pad raw text BEFORE applying styles to ensure consistent column widths
+                const titlePadded = item.title.padEnd(28);
+                const descPadded = item.description.padEnd(36);
+                const pagesText = `(${String(item.pages.length)} ${item.pages.length === 1 ? 'page' : 'pages'})`;
+                const pagesPadded = pagesText.padStart(10);
+                // Apply styles after padding
+                const title = isSelected ? styles.primary(titlePadded) : titlePadded;
+                const desc = styles.muted(descPadded);
+                const pages = styles.muted(pagesPadded);
+                return `${prefix}${title} ${desc} ${pages}`;
+            },
+            footerHints: (searchMode) => {
+                if (searchMode) {
+                    return 'Type to filter · ↑↓/jk Navigate · Enter View · Esc Exit search';
+                }
+                return 'Tab Filter · ↑↓/jk · ←→/hl Pages · / Search · Enter View · q/Esc Close';
+            },
+            emptyMessage: 'No tutorials available.',
+            noResultsMessage: 'No tutorials match the search.',
+            showCount: false,
+        });
+        // Override minHeight for tutorial content
+        this.minHeight = 22;
     }
-    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));
+    /**
+     * Build items on first render when styles are available.
+     * This is a workaround since we need styles to build styled content.
+     */
+    buildItemsIfNeeded() {
+        if (this.state.items.length > 0)
+            return;
+        const styles = this.getStyles();
+        const tabs = buildTutorialContent(styles);
+        // Flatten tutorials into a single array with tabId
+        const items = [];
+        for (const tab of tabs) {
+            for (const item of tab.items) {
+                items.push({
+                    ...item,
+                    tabId: tab.id,
+                });
+            }
         }
-        const screen = this.screenStack.current();
-        return screen?.render() ?? [];
+        this.state.items = items;
+        this.state.filteredItems = items.filter((item) => this.listConfig.filterByTab(item, this.listConfig.tabs[0]?.id ?? 'basics'));
     }
-    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);
-        }
+    /**
+     * Override render to build items on first call.
+     */
+    render(context) {
+        // Cache styles first so buildItemsIfNeeded can use them
+        this.styles = context.styles;
+        this.termWidth = context.width;
+        // Build items if not yet built
+        this.buildItemsIfNeeded();
+        // Render using parent
+        return super.render(context);
+    }
+    createDetailScreen(item) {
+        const styles = this.getStyles();
+        return new ViewingScreen(item, styles, () => this.termWidth);
     }
 }