Raibid Labs Documentation

PULL_REQUEST_TEMPLATE

5 min read

Interactive Tutorial and Onboarding System

Implements Issue #25: Interactive Tutorial and Onboarding

Overview

This PR adds a comprehensive interactive tutorial and onboarding system for Scarab Terminal, making it easier for new users to learn key features and get productive quickly.

Changes

1. Interactive In-Terminal Tutorial System

New Files:

  • crates/scarab-client/src/tutorial/mod.rs - Tutorial plugin framework
  • crates/scarab-client/src/tutorial/steps.rs - 8-step tutorial definitions
  • crates/scarab-client/src/tutorial/ui.rs - Tutorial UI rendering
  • crates/scarab-client/src/tutorial/validation.rs - Step validation helpers

Features:

  • ✅ 8-step guided tour (Welcome → Navigation → Scrollback → Link Hints → Palette → Plugins → Config → Completion)
  • ✅ Interactive step validation (users must complete actions)
  • ✅ Progress tracking with persistence (~/.config/scarab/tutorial_progress.json)
  • ✅ Launches automatically on first run
  • ✅ Replayable with --tutorial flag
  • ✅ Beautiful ASCII art UI with progress bar
  • ✅ Keyboard navigation (Space/Enter: Next, Backspace: Previous, ESC: Skip)

2. Written Tutorials

New Documentation:

  • docs/tutorials/01-getting-started.md - Installation and first 5 minutes
  • docs/tutorials/02-customization.md - Themes, fonts, keybindings, performance
  • docs/tutorials/03-workflows.md - Git, Docker, SSH, multi-language development

Coverage:

  • Complete installation instructions for Ubuntu, Fedora, Arch
  • Step-by-step quick start guide
  • Comprehensive configuration reference
  • Real-world workflow examples
  • Troubleshooting guide

3. Video Screencast Scripts

New Scripts:

  • scripts/record-videos.sh - Automated video recording for all 3 screencasts
  • docs/videos/README.md - Video recording instructions and guidelines

Videos (scripts ready, need recording):

  1. Scarab in 2 Minutes - Quick feature showcase
  2. Your First Plugin - Step-by-step plugin creation
  3. Advanced Workflows - Power user tips

4. Animated GIF Demo Scripts

New Scripts:

  • scripts/record-demos.sh - Automated GIF recording for all demos
  • docs/assets/demos/README.md - Demo recording instructions

Demos (scripts ready, need recording):

  • link-hints-demo.gif - Link hints feature
  • command-palette.gif - Command palette usage
  • plugin-install.gif - Plugin installation
  • theme-switch.gif - Theme switching
  • split-panes.gif - Split panes (placeholder for future)

5. Updated README

Changes to README.md:

  • Added “Visual Demos” section at top with GIF placeholders
  • Added links to video tutorials
  • Updated “Quick Start” to mention interactive tutorial
  • Added tutorial step list
  • Improved documentation navigation

6. Code Integration

Updated Files:

  • crates/scarab-client/src/lib.rs - Exports tutorial module
  • crates/scarab-client/Cargo.toml - Added serde_json dependency (for tutorial progress)

Testing

Manual Testing

Tutorial System:

  • Launch client on fresh install - tutorial starts automatically
  • Complete tutorial step-by-step
  • Skip tutorial with ESC
  • Replay tutorial with --tutorial flag
  • Verify progress persistence

Documentation:

  • Follow “Getting Started” guide from scratch
  • Test all configuration examples
  • Verify all links work

Unit Tests

All tutorial modules include comprehensive unit tests:

cargo test -p scarab-client tutorial::

Tests cover:

  • Tutorial progression (next/previous/skip)
  • Step validation logic
  • Progress persistence
  • UI text wrapping

Demo Recording

To create the actual GIF demos and videos:

# Install prerequisites
pip install asciinema
cargo install agg
npm install -g asciicast2mp4  # Optional, for videos
 
# Record demos (creates ~20-30MB of GIFs)
chmod +x scripts/record-demos.sh
./scripts/record-demos.sh
 
# Record videos (creates ~50-100MB of MP4s)
chmod +x scripts/record-videos.sh
./scripts/record-videos.sh

Note: Actual demo files are NOT included in this PR to keep the commit size reasonable. They can be recorded and added later, or hosted externally (YouTube, GitHub Releases).

Documentation Structure

docs/
├── tutorials/
│   ├── 01-getting-started.md       # NEW: Installation & first steps
│   ├── 02-customization.md         # NEW: Themes, config, keybindings
│   └── 03-workflows.md             # NEW: Git, Docker, SSH workflows
├── videos/
│   ├── README.md                   # NEW: Video recording guide
│   ├── scarab-2min-demo.mp4        # TODO: Record
│   ├── first-plugin-tutorial.mp4   # TODO: Record
│   └── advanced-workflows.mp4      # TODO: Record
└── assets/
    └── demos/
        ├── README.md               # NEW: Demo recording guide
        ├── PLACEHOLDER.md          # NEW: Placeholder info
        ├── link-hints-demo.gif     # TODO: Record
        ├── command-palette.gif     # TODO: Record
        ├── plugin-install.gif      # TODO: Record
        ├── theme-switch.gif        # TODO: Record
        └── split-panes.gif         # TODO: Record

Code Structure

crates/scarab-client/src/tutorial/
├── mod.rs          # Tutorial system core, Bevy plugin, state machine
├── steps.rs        # 8 tutorial step definitions
├── ui.rs           # ASCII art rendering and UI
└── validation.rs   # Step validation helpers

Success Criteria

  • Interactive tutorial completes in < 5 minutes
  • All 3 video scripts created
  • 5+ demo scripts created
  • 3+ written tutorials published
  • README updated with visual demos
  • Actual GIFs/videos recorded (post-PR)
  • New users report easier onboarding (post-release survey)

Breaking Changes

None. All changes are additive.

Migration Guide

No migration needed. Existing users will see:

  • Interactive tutorial on next client launch (can skip with ESC)
  • New --tutorial flag available
  • New documentation in docs/tutorials/

Performance Impact

  • Tutorial system adds ~5KB to client binary
  • Tutorial progress file: ~500 bytes
  • No runtime impact when tutorial is not active

Future Enhancements

  • Add tutorial for tabs/splits (when feature is implemented)
  • Localization support (i18n)
  • Interactive playground mode
  • Video tutorials embedded in terminal
  • Completion badges/achievements
  • Closes #25 (Interactive Tutorial and Onboarding)
  • Related to #26 (Complete Reference Documentation)
  • Related to #27 (Plugin Development Documentation)

Checklist

  • Code follows project style guidelines
  • All tests pass locally
  • Documentation updated
  • Commit messages follow convention
  • No merge conflicts
  • Demo videos recorded (post-PR task)
  • PR description is complete

Screenshots

Tutorial Welcome Screen:

┌─────────────────────────────────────────────────────┐
│                   SCARAB TUTORIAL                   │
│                   Step 1 of 8                       │
├─────────────────────────────────────────────────────┤
│                                                     │
│  WELCOME TO SCARAB TERMINAL!                        │
│                                                     │
│  Scarab is a next-generation GPU-accelerated       │
│  terminal emulator with F# plugins and zero-copy   │
│  IPC.                                               │
│                                                     │
│  This quick tutorial will guide you through the    │
│  key features.                                      │
│                                                     │
│  It will take about 5 minutes to complete.         │
│                                                     │
│  ▶ Press SPACE or ENTER to continue                │
│                                                     │
│  💡 Hint: You can skip this tutorial anytime by    │
│           pressing ESC                              │
│                                                     │
│  ██████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   │
│  12% complete                                       │
│                                                     │
│  [ESC: Skip]  [BACKSPACE: Back]  [SPACE/ENTER: Next →] │
└─────────────────────────────────────────────────────┘

Review Notes

Please review:

  1. Tutorial step flow and UX
  2. Documentation clarity and completeness
  3. Code organization and testing
  4. Recording script accuracy

Post-Merge Tasks

  1. Record actual GIF demos (can be done by any contributor)
  2. Record video screencasts
  3. Upload videos to YouTube
  4. Update README with actual YouTube links
  5. Announce new tutorial system in release notes

Thank you for reviewing!

Graph View