QuantumLearning/FIRST_RUN.md

First Run

Use this the first time you open the platform, or anytime you want a clean local restart.

Checklist

1. If this is a fresh Mac or a fresh clone, bootstrap the repo first:

   bash ./scripts/app.sh bootstrap
   

2. Check the local state:

   bash ./scripts/app.sh status
   bash ./scripts/app.sh validate --quick
   

3. Start the repo-local server:

   bash ./scripts/app.sh start --open
   

   If JupyterLab later looks haunted by old tabs or stale session state, reset the repo-local Jupyter state and start again:

   bash ./scripts/app.sh reset-state
   bash ./scripts/app.sh start --open
   

4. Open the localhost URL printed by the script. It should land on notebooks/START_HERE.ipynb.

5. Confirm the kernel in the top-right corner is QuantumLearning (.venv).

6. Run the cells in START_HERE.ipynb from top to bottom and follow its explicit next-notebook handoff to COURSE_BLUEPRINT.ipynb.

7. From that point onward, do not guess from the filesystem. Follow the explicit next-notebook navigation inside each notebook.

8. The required mainline flow is: START_HERE.ipynb -> COURSE_BLUEPRINT.ipynb -> foundations -> qiskit_engineering -> algorithms -> professional -> COURSE_COMPLETE.ipynb

9. Inside every module, the required local flow is: lecture.ipynb -> lab.ipynb -> problems.ipynb -> studio.ipynb

10. Inside every notebook, complete the MANDATORY cells in order. Treat FACULTATIVE cells as optional extensions only.

11. META cells are route/objective/pacing guidance, not the technical payload. They are intentionally colored differently inside the notebooks.

12. The route notebooks START_HERE, COURSE_BLUEPRINT, and COURSE_COMPLETE should not contain facultative detours.

Expected Local Behavior

• Everything runs from the repo-local .venv.
• Jupyter config, runtime files, and notebook settings stay inside this project.
• The launcher hides the broken machine-level Homebrew node path so JupyterLab starts cleanly on this machine.
• No IBM token is required for the main workflow.
• The Foundations, Qiskit Engineering, Algorithmic Design, and Professional Design bands are rebuilt into Lecture / Lab / Problems / Studio bundles on top of a professional apprenticeship model.
• Difficulty 1-3 is reserved for mandatory cells. Difficulty 4-10 appears only on facultative extensions.

Smoke Check

If you want a quick terminal check before opening the browser:

bash ./scripts/app.sh validate --quick

For the full operational guide, see OPERATIONS.md.