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
   bash ./scripts/app.sh bootstrap
   ```

2. Check the local state:

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

3. Start the repo-local server:

   ```bash
   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
bash ./scripts/app.sh validate --quick
```

For the full operational guide, see [OPERATIONS.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/OPERATIONS.md).