# 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
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:

```bash
./.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:

1. `AGENT_CONTEXT.md`
2. `README.md`
3. `OPERATIONS.md`
4. `FIRST_RUN.md`
5. `configs/curriculum.toml`
6. `configs/mastery_blueprint.toml`
7. `tests/test_course_flow.py`

Then inspect current repo state:

```bash
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.