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:

brew install python@3.12

or install Python 3.12 from python.org.

Then bootstrap the repo:

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 ./scripts/bootstrap_mac.sh --run-validation

If you want to delay the browser download:

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

Start And Use The Course

Start JupyterLab:

./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 ./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 ./scripts/run_validation.sh --quick

This runs:

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

Standard validation:

bash ./scripts/run_validation.sh --standard

This runs the full pytest suite without coverage reporting.

Release-style validation:

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 ./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.