aitutor: Instructions file for Codex

AGENTS.md

Project Overview

AITutor is an interactive terminal-based tutorial for AI coding concepts, built with Go and the Charm ecosystem (Bubbletea, Lipgloss, Bubbles). It teaches through theory, interactive visualizations, and quizzes across 17 lessons in 3 tiers (Beginner, Intermediate, Advanced).

Architecture

• Entry point: main.go — blank-imports all content packages to trigger init() lesson registration
• App model: internal/app/app.go — root Bubbletea model orchestrating header, footer, sidebar, lesson model, progress, welcome screen, and help overlay
• Lesson state machine: internal/lesson/model.go — phases: Theory → Visualization → Quiz → Complete
• Content: internal/content/{beginner,intermediate,advanced}/ — each file registers a LessonDef via init()
• Visualizations: internal/viz/ — each viz implements the viz.Model interface (Init/Update/View)
• Quiz: internal/quiz/ — supports MultipleChoice, FillBlank, and Ordering question types
• Progress: internal/progress/ — persists to ~/.aitutor/progress.json
• Types: pkg/types/types.go — shared types to avoid circular imports

Key Patterns

Adding a New Lesson

1. Create internal/content/<tier>/NN_topic.go
2. In init(), call lesson.Register(types.LessonDef{...}) with ID, Title, Tier, Theory, VizBuilder, and Questions
3. Create the visualization in internal/viz/ implementing viz.Model interface
4. The lesson auto-registers — no wiring needed
5. Update internal/ui/header.go default Total if needed (it gets overridden at runtime but keeps the default accurate)

VizBuilder Uses interface{}

VizBuilder returns interface{} (not viz.Model) to avoid circular imports between types and viz packages. The lesson package does the type assertion.

Key Handling

• App-level keys (quit, tab, n/p, →/← for phase navigation, ?) are handled in app.go
• → (right arrow) advances phases from any phase — this is the primary "next phase" key
• ← (left arrow) and Backspace go back a phase
• Enter advances from Theory phase, but in Viz/Quiz phases it falls through to the viz/quiz for interaction
• Tab is reserved for sidebar toggle — visualizations must not use Tab
• Visualizations should use h/l for horizontal navigation, not left/right arrows (reserved for phase nav)