# 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 `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 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 reset-state 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/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 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 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 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` 5. if the UI still looks stale, run `bash ./scripts/app.sh reset-state` 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. ## Agent Restart Handoff If you restart a coding agent in this repo and want it to get up to speed quickly, use: - [AGENT_CONTEXT.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/AGENT_CONTEXT.md) - [AGENT_RESTART_PROTOCOL.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/AGENT_RESTART_PROTOCOL.md) Those files are the repo-local handoff layer. They exist because session memory does not persist across restarts. ## 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 ...`.