Agent Context

This file exists so a restarted coding agent can get up to speed quickly without relying on vanished session memory.

Project Identity

Project: QuantumLearning
Goal: local-first, notebook-first Qiskit course that trains a beginner into an independent hardware-aware quantum circuit designer
Main constraint: the course now has one supported walkthrough only

Official Learner Route

The only supported end-to-end path is:

START_HERE.ipynb -> COURSE_BLUEPRINT.ipynb -> foundations -> qiskit_engineering -> algorithms -> professional -> COURSE_COMPLETE.ipynb

Rules:

META cells are route/objective/pacing guidance
MANDATORY cells are the official walkthrough
FACULTATIVE cells are optional extensions only
difficulty 1-3 is reserved for mandatory cells
difficulty 4-10 is reserved for facultative cells
START_HERE, COURSE_BLUEPRINT, and COURSE_COMPLETE are route notebooks and must not contain facultative extensions

Consumer Operations

Normal user commands:

bash ./scripts/app.sh bootstrap
bash ./scripts/app.sh start --open
bash ./scripts/app.sh status
bash ./scripts/app.sh restart
bash ./scripts/app.sh stop
bash ./scripts/app.sh reset-state
bash ./scripts/app.sh validate --quick

Validation Reality

In normal local use, the project supports:

unit and config tests
pedagogy and route tests
browser UX tests
notebook execution tests

One operational caveat from the last build cycle:

the single monolithic pytest --cov=quantum_learning --cov-report=term-missing -q invocation can hang intermittently in this agent environment
the reliable segmented validation that passed was:

./.venv/bin/python -m pytest tests/test_course_flow.py tests/test_project_experience.py tests/test_notebook_pedagogy.py -q
./.venv/bin/python -m pytest tests/test_browser_ux.py -q
./.venv/bin/python -m pytest tests/test_notebook_execution.py -q
./.venv/bin/python -m pytest -q -m "not browser and not notebook"
./.venv/bin/python -m ruff check src tests scripts

Treat that as the trustworthy fallback if the aggregate coverage run stalls again.

Files A Restarted Agent Should Read First

Read these before making assumptions:

AGENT_CONTEXT.md
README.md
OPERATIONS.md
FIRST_RUN.md
configs/curriculum.toml
configs/mastery_blueprint.toml
tests/test_course_flow.py

Then inspect current repo state:

git status --short --branch
git log --oneline -5

Files That Matter Most

learner contract: README.md, FIRST_RUN.md, OPERATIONS.md
route logic: src/quantum_learning/course_flow.py, scripts/harden_course_flow.py
curriculum config: configs/curriculum.toml, configs/mastery_blueprint.toml
notebook generators: scripts/build_course_notebooks.py, scripts/build_world_class_bundle.py, scripts/build_*_band.py
route/pedagogy tests: tests/test_course_flow.py, tests/test_notebook_pedagogy.py, tests/test_project_experience.py

Current Architectural Judgement

The last major correction was pedagogical, not mathematical:

meta notebooks had become noisy and self-referential
route notebooks now contain no facultative detours
raw widget-wrapper code is hidden from learners where possible

If a future change threatens the single-route contract, treat that as a regression.

3.3 KiB Raw Permalink Blame History