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

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

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

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