QuantumLearning/OPERATIONS.md

# Operations

This file is the self-service operations manual for `QuantumLearning`. It is written to match the repo as it actually exists now, not a hypothetical future state.

## Operating Model

The project is intentionally local-first and repo-local:

- Python environment lives in `.venv/`
- Jupyter config and runtime live in `.jupyter_config/`, `.jupyter_data/`, `.jupyter_runtime/`, `.ipython/`, and `.cache/matplotlib/`
- Playwright browser runtime lives in `.playwright-browsers/`
- validation artifacts live in `.tmp_test_artifacts/`

That means the day-to-day operational commands are all inside this repo.

## Bootstrap On A New Mac

Prerequisites:

1. macOS
2. Python `3.12`
3. internet access for the initial dependency and browser download

If `python3.12` is missing, install it first.
Typical options:

```bash
brew install python@3.12
```

or install Python `3.12` from `python.org`.

Then bootstrap the repo:

```bash
cd /path/to/QuantumLearning
bash ./scripts/bootstrap_mac.sh
```

That script will:

- create `.venv/` if needed
- install the Python dependencies from `pyproject.toml`
- install the project-local Playwright Chromium runtime into `.playwright-browsers/`

If you want the bootstrap to finish with a full validation run:

```bash
bash ./scripts/bootstrap_mac.sh --run-validation
```

If you want to delay the browser download:

```bash
bash ./scripts/bootstrap_mac.sh --skip-browser
```

## Start And Use The Course

Start JupyterLab:

```bash
./scripts/start_jupyter.sh
```

Open the exact localhost URL printed by the script. Do not guess the port; Jupyter will automatically move to the next free port if the requested one is already occupied.

Use the course in this order:

1. `notebooks/COURSE_BLUEPRINT.ipynb`
2. each module as `lecture -> lab -> problems -> studio`

## Monitoring The Project

Use the repo-native status script:

```bash
bash ./scripts/project_status.sh
```

It reports:

- current git branch and commit
- whether the worktree is clean or dirty
- whether `.venv/` exists and which Python version it uses
- whether the project-local Playwright browser runtime is installed
- whether a repo-local Jupyter server is running and, if so, its full URL

If you lose the Jupyter URL, `bash ./scripts/project_status.sh` is the fastest recovery path.

In restricted automation sandboxes, the script may report that the live process probe is unavailable. In a normal terminal on your Mac, it will report the running server directly when the runtime file and process are both visible.

## Validation Modes

Quick local validation:

```bash
bash ./scripts/run_validation.sh --quick
```

This runs:

- `ruff check src tests scripts`
- `pytest -m "not browser and not notebook"`

Standard validation:

```bash
bash ./scripts/run_validation.sh --standard
```

This runs the full pytest suite without coverage reporting.

Release-style validation:

```bash
bash ./scripts/run_validation.sh --full
```

This runs:

- `ruff check src tests scripts`
- full pytest suite
- coverage reporting

In restricted automation sandboxes, the browser and notebook execution suites may skip because localhost kernel and browser ports are blocked. In a normal terminal on your Mac, the same command should run those suites instead of skipping them.

At the current state of the repo, the full validation suite includes:

- curriculum/config/runtime tests
- notebook pedagogy tests
- notebook execution tests
- real JupyterLab browser workflow validation
- assessment and capstone validation tests

## What The Browser Workflow Validation Now Covers

The browser suite no longer stops at “page opened.”

It now validates learner-style flows such as:

- opening notebooks through JupyterLab
- running all notebook cells
- answering a multiple-choice quiz
- editing an `editable_circuit_lab` code cell and re-rendering it
- completing an evidence checklist
- filling a feedback iteration panel
- moving rubric sliders and observing the grading summary update

## Recovery Checklist

If something feels wrong, use this order:

1. `bash ./scripts/project_status.sh`
2. `bash ./scripts/run_validation.sh --quick`
3. if needed, `bash ./scripts/run_validation.sh --full`
4. restart Jupyter with `./scripts/start_jupyter.sh`

If `.venv/` is missing or broken, re-run:

```bash
bash ./scripts/bootstrap_mac.sh
```

## Another-Mac Transfer Pattern

The clean transfer model is:

1. clone or copy the repo to the new Mac
2. make sure Python `3.12` exists
3. run `bash ./scripts/bootstrap_mac.sh`
4. run `bash ./scripts/run_validation.sh --quick`
5. run `./scripts/start_jupyter.sh`

That is the intended self-service installation path. You do not need agent support for normal setup, validation, status checks, or Jupyter startup.