Quick orientation for AI coding agents

Architecture & Conventions

Standard library only: Lessons in ultimatepython/ strictly use the Python standard library. No external runtime dependencies, external services, or network calls.
Lesson structure: Docstring, helper definitions, parameterless idempotent main() with assertions for verification, and if __name__ == "__main__": main().
Runner discovery: runner.py dynamically discovers modules under ultimatepython/ and executes main().
Web UI (ui/): An Astro + TypeScript application for browsing lessons. Lessons are parsed by ui/parse_lessons.py.

Run ./pre-commit.sh to run the full Python verification suite:

Lint & Format: ruff check and ruff format
Type Checking: mypy ultimatepython check_readmes.py runner.py
README Sync: python check_readmes.py (verifies header hierarchy and lesson links)
Tests & Coverage: coverage run runner.py and coverage report (target >= 80%)
Single Lesson: python ultimatepython/<category>/<module>.py
UI Checks: npm run lint (astro check) and npm run build in ui/