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.

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

6. Run Kernel -> Restart Kernel and Run All Cells... inside notebooks/COURSE_BLUEPRINT.ipynb.

7. Read the rebuilt Foundations band in this order: module_01_principles_and_circuit_literacy module_02_qubit_and_statevector_intuition module_03_gates_and_measurement and inside each module use: lecture.ipynb -> lab.ipynb -> problems.ipynb -> studio.ipynb.

8. Continue into the rebuilt Qiskit Engineering band: module_01_circuit_construction_and_analysis module_02_transpilation_and_visualization module_03_simulation_and_noise_models again using: lecture.ipynb -> lab.ipynb -> problems.ipynb -> studio.ipynb.

9. Continue into the rebuilt Algorithmic Design band: module_01_deutsch_family module_02_bernstein_vazirani module_03_qft module_04_grover again using: lecture.ipynb -> lab.ipynb -> problems.ipynb -> studio.ipynb.

10. Continue into the rebuilt Professional Design band: module_01_qiskit_patterns module_02_hardware_aware_redesign module_03_noise_aware_verification module_04_capstone_design_review again using: lecture.ipynb -> lab.ipynb -> problems.ipynb -> studio.ipynb.

11. Use notebooks/PROFESSIONAL_PATH.ipynb when you want the full mastery-model context.

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.

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.