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

That command 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/app.sh bootstrap --run-validation
```

If you want to delay the browser download:

```bash
bash ./scripts/app.sh bootstrap --skip-browser
```

## Start And Use The Course

Start the app:

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

That starts the repo-local Jupyter server as a detached background service, prints the exact URL, cleans up stale runtime files when needed, and opens it in the default browser.

If you run the launcher from an automation shell that reaps background child processes when the shell exits, use foreground mode instead:

```bash
bash ./scripts/app.sh start --foreground
```

Other normal consumer commands:

```bash
bash ./scripts/app.sh status
bash ./scripts/app.sh restart
bash ./scripts/app.sh stop
bash ./scripts/app.sh logs -f
```

If you want foreground mode for debugging:

```bash
bash ./scripts/app.sh start --foreground
```

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/app.sh status
```

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

This runs:

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

Standard validation:

```bash
bash ./scripts/app.sh validate --standard
```

This runs the full pytest suite without coverage reporting.

Release-style validation:

```bash
bash ./scripts/app.sh validate --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/app.sh status`
2. `bash ./scripts/app.sh validate --quick`
3. if needed, `bash ./scripts/app.sh validate --full`
4. restart Jupyter with `bash ./scripts/app.sh restart`

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

```bash
bash ./scripts/app.sh bootstrap
```

## 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/app.sh bootstrap`
4. run `bash ./scripts/app.sh validate --quick`
5. run `bash ./scripts/app.sh start --open`

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

## Underlying Plumbing

The lower-level scripts still exist for direct use or debugging:

- `bash ./scripts/bootstrap_mac.sh`
- `bash ./scripts/project_status.sh`
- `bash ./scripts/run_validation.sh --quick`
- `./scripts/start_jupyter.sh --foreground`

Those are implementation details now. The normal consumer interface is `bash ./scripts/app.sh ...`.