# CLAUDE.md -- cde-onboard

## Project Overview

cde-onboard is a Python Textual TUI application that provides interactive, hands-on tutorials for onboarding engineers onto ONA Environments (cloud developer environments). It guides users through six lessons covering dev containers, environment setup, tasks, services, dotfiles, and multi-repo workflows, scaffolding real configuration files into a practice directory as the user progresses.

## Tech Stack

- **Python 3.11+**
- **Textual** (>=1.0) -- TUI framework for the interactive terminal UI
- **Rich** (>=13.0) -- rich text and syntax highlighting in the terminal
- **Typer** (>=0.12) -- CLI entry point and argument parsing
- **Pydantic v2** (>=2.0) -- data models and validation
- **PyYAML** (>=6.0) -- YAML support
- **Hatchling** -- build backend
- **pytest** + **pytest-asyncio** -- testing
- **Ruff** -- linting
- **mypy** -- type checking

## How to Run

### Install
```bash
cd /data/projects/ona-user-onboarding
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

### Launch TUI
```bash
cde-onboard              # Interactive TUI
cde-onboard --lesson 3   # Jump to lesson 3
cde-onboard --list       # Print lessons table (non-TUI)
cde-onboard --reset      # Clear progress
```

### Run Tests
```bash
pytest tests/ -v
```

### Lint and Type Check
```bash
ruff check src/ tests/
mypy src/cde_onboard/
```

## Architecture

```
CLI (cli.py / Typer)
  |
  v
OnboardApp (app.py / Textual App)
  |
  +-- WelcomeScreen        -- landing page with Start / Choose / Quit
  +-- LessonMenuScreen     -- picker showing all 6 lessons with completion status
  +-- LessonScreen(N)      -- main teaching view with steps, code panels, scaffold button
  +-- CompletionScreen     -- celebration when all lessons are done
  |
  +-- Widgets:
  |     LessonSidebar      -- left sidebar with progress indicators
  |     StepView           -- renders one teaching step
  |     CodePanel           -- syntax-highlighted code block (Rich Syntax)
  |     InfoPanel           -- callout/tip box
  |
  +-- Lessons (lessons/):
  |     BaseLesson (ABC)   -- meta(), steps(), scaffold_files()
  |     lesson_01 .. 06    -- concrete lesson implementations
  |
  +-- Scaffolder           -- creates practice files from templates in content/templates/
  +-- ProgressManager      -- load/save/reset JSON progress at ~/.cde-onboard/progress.json
```

The app uses a screen-stack navigation model. `ProgressManager` is instantiated once at the `OnboardApp` level and passed to all screens.

## Key Rules (ONA-Specific)

These rules MUST be followed in all lesson content, templates, and code:

1. **Config path**: `.ona/automations.yaml` (not `.gitpod.yml`)
2. **Services use nested commands**: `commands:` -> `start:`, `ready:`, `stop:`
3. **Tasks use flat command**: `command:` (not nested under `commands:`)
4. **network_mode: host**: REQUIRED on ALL Docker Compose services
5. **CLI**: Use `gitpod` prefix (e.g., `gitpod automations task start`, `gitpod user dotfiles set`)
6. **Dotfiles location**: Cloned to `~/dotfiles`
7. **Multi-repo convention**: Clone to `/workspaces/<repo-name>`
8. **GitLab URLs only**: All example repo URLs use `gitlab.example.com`, never GitHub
9. **Triggers**: `postDevcontainerStart`, `postEnvironmentStart`, `prebuild`, `manual`
10. **GitLab OAuth**: ONA authenticates via OAuth (one-time setup). No PATs needed.
11. **VS Code Browser only**: Primary connection method from the ONA dashboard. Do NOT reference VS Code Desktop or SSH.

## File Structure

```
/data/projects/ona-user-onboarding/
├── pyproject.toml                          # Project metadata, deps, entry points
├── CLAUDE.md                               # This file
├── PLAN.md                                 # Detailed implementation plan
├── src/cde_onboard/
│   ├── __init__.py                         # Package init, __version__
│   ├── __main__.py                         # python -m cde_onboard entry
│   ├── cli.py                              # Typer CLI: --lesson, --list, --reset
│   ├── app.py                              # Textual App (OnboardApp)
│   ├── constants.py                        # Paths, app metadata, lesson slugs
│   ├── models.py                           # Pydantic: CodeBlock, LessonStep, LessonMeta,
│   │                                       #           ScaffoldFile, ProgressData
│   ├── progress.py                         # ProgressManager (load/save/reset JSON)
│   ├── scaffolder.py                       # scaffold_lesson() + template reader
│   ├── screens/
│   │   ├── welcome.py                      # WelcomeScreen
│   │   ├── lesson_menu.py                  # LessonMenuScreen + LessonMenuItem
│   │   ├── lesson.py                       # LessonScreen (teaching + scaffold)
│   │   └── completion.py                   # CompletionScreen (all done)
│   ├── widgets/
│   │   ├── lesson_sidebar.py               # LessonSidebar
│   │   ├── step_view.py                    # StepView
│   │   ├── code_panel.py                   # CodePanel (Rich Syntax)
│   │   └── info_panel.py                   # InfoPanel (callout box)
│   ├── lessons/
│   │   ├── __init__.py                     # Registry: get_all_lessons(), get_lesson(N)
│   │   ├── base.py                         # BaseLesson ABC
│   │   ├── lesson_01_devcontainer.py       # Dev Container Basics
│   │   ├── lesson_02_first_environment.py  # First ONA Environment
│   │   ├── lesson_03_tasks.py              # Tasks in automations.yaml
│   │   ├── lesson_04_services.py           # Services + Docker Compose
│   │   ├── lesson_05_dotfiles.py           # Dotfiles repo setup
│   │   └── lesson_06_multi_repo.py         # Multi-repo management
│   ├── content/
│   │   └── templates/                      # Scaffolded file templates
│   │       ├── devcontainer_basic.json
│   │       ├── devcontainer_multi_repo.json
│   │       ├── automations_task.yaml
│   │       ├── automations_service.yaml
│   │       ├── docker_compose_service.yaml
│   │       ├── dotfiles_install.sh
│   │       ├── dotfiles_bashrc
│   │       └── dotfiles_gitconfig
│   └── styles/
│       └── app.tcss                        # Textual CSS stylesheet
└── tests/
    ├── conftest.py                         # Shared fixtures
    ├── test_models.py                      # Pydantic model tests
    ├── test_progress.py                    # ProgressManager tests
    ├── test_scaffolder.py                  # Scaffolder tests
    └── test_app.py                         # Textual app TUI tests
```

## Progress Storage

Progress is saved to `~/.cde-onboard/progress.json`. The `ProgressManager` accepts an optional `path` argument for testing with `tmp_path`.

## Scaffolding

Templates live in `src/cde_onboard/content/templates/` and are read via `importlib.resources`. Scaffolded files are written to `./cde-onboard-practice/lesson-NN-<slug>/` in the user's current working directory.
