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

If you want to delay the browser download:

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

Start And Use The Course

Start the app:

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 notebooks/START_HERE.ipynb 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 ./scripts/app.sh start --foreground

Other normal consumer commands:

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

If you want foreground mode for debugging:

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

Use the course in this order:

1. notebooks/START_HERE.ipynb
2. notebooks/COURSE_BLUEPRINT.ipynb
3. each module as lecture -> lab -> problems -> studio
4. notebooks/COURSE_COMPLETE.ipynb

Operational rule inside the notebooks:

• complete MANDATORY cells in order
• use FACULTATIVE cells only as optional extensions
• read META cells as route/objective guidance, not as part of the technical payload
• expect no facultative extensions inside the route notebooks START_HERE, COURSE_BLUEPRINT, or COURSE_COMPLETE

Monitoring The Project

Use the repo-native status script:

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
• whether saved Jupyter UI state is still present and how to reset it

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.

If JupyterLab reopens old tabs or appears to remember stale notebook activity, that is usually saved workspace state rather than a still-running repo-local server. Clear it with:

bash ./scripts/app.sh reset-state

The consumer rule is simple: after START_HERE, follow the explicit next-notebook navigation inside the notebooks themselves instead of browsing for your own path.

Validation Modes

Quick local validation:

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

This runs:

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

Standard validation:

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

This runs the full pytest suite without coverage reporting.

Release-style validation:

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
5. if the UI still looks stale, run bash ./scripts/app.sh reset-state

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

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