Add durable agent restart handoff docs

AGENT_CONTEXT.md

@@ -0,0 +1,99 @@
+# Agent Context
+
+This file exists so a restarted coding agent can get up to speed quickly without relying on vanished session memory.
+
+## Project Identity
+
+- Project: `QuantumLearning`
+- Goal: local-first, notebook-first Qiskit course that trains a beginner into an independent hardware-aware quantum circuit designer
+- Main constraint: the course now has **one** supported walkthrough only
+
+## Official Learner Route
+
+The only supported end-to-end path is:
+
+`START_HERE.ipynb -> COURSE_BLUEPRINT.ipynb -> foundations -> qiskit_engineering -> algorithms -> professional -> COURSE_COMPLETE.ipynb`
+
+Rules:
+
+- `META` cells are route/objective/pacing guidance
+- `MANDATORY` cells are the official walkthrough
+- `FACULTATIVE` cells are optional extensions only
+- difficulty `1-3` is reserved for mandatory cells
+- difficulty `4-10` is reserved for facultative cells
+- `START_HERE`, `COURSE_BLUEPRINT`, and `COURSE_COMPLETE` are route notebooks and must not contain facultative extensions
+
+## Consumer Operations
+
+Normal user commands:
+
+```bash
+bash ./scripts/app.sh bootstrap
+bash ./scripts/app.sh start --open
+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 validate --quick
+```
+
+## Validation Reality
+
+In normal local use, the project supports:
+
+- unit and config tests
+- pedagogy and route tests
+- browser UX tests
+- notebook execution tests
+
+One operational caveat from the last build cycle:
+
+- the single monolithic `pytest --cov=quantum_learning --cov-report=term-missing -q` invocation can hang intermittently in this agent environment
+- the reliable segmented validation that passed was:
+
+```bash
+./.venv/bin/python -m pytest tests/test_course_flow.py tests/test_project_experience.py tests/test_notebook_pedagogy.py -q
+./.venv/bin/python -m pytest tests/test_browser_ux.py -q
+./.venv/bin/python -m pytest tests/test_notebook_execution.py -q
+./.venv/bin/python -m pytest -q -m "not browser and not notebook"
+./.venv/bin/python -m ruff check src tests scripts
+```
+
+Treat that as the trustworthy fallback if the aggregate coverage run stalls again.
+
+## Files A Restarted Agent Should Read First
+
+Read these before making assumptions:
+
+1. `AGENT_CONTEXT.md`
+2. `README.md`
+3. `OPERATIONS.md`
+4. `FIRST_RUN.md`
+5. `configs/curriculum.toml`
+6. `configs/mastery_blueprint.toml`
+7. `tests/test_course_flow.py`
+
+Then inspect current repo state:
+
+```bash
+git status --short --branch
+git log --oneline -5
+```
+
+## Files That Matter Most
+
+- learner contract: `README.md`, `FIRST_RUN.md`, `OPERATIONS.md`
+- route logic: `src/quantum_learning/course_flow.py`, `scripts/harden_course_flow.py`
+- curriculum config: `configs/curriculum.toml`, `configs/mastery_blueprint.toml`
+- notebook generators: `scripts/build_course_notebooks.py`, `scripts/build_world_class_bundle.py`, `scripts/build_*_band.py`
+- route/pedagogy tests: `tests/test_course_flow.py`, `tests/test_notebook_pedagogy.py`, `tests/test_project_experience.py`
+
+## Current Architectural Judgement
+
+The last major correction was pedagogical, not mathematical:
+
+- meta notebooks had become noisy and self-referential
+- route notebooks now contain no facultative detours
+- raw widget-wrapper code is hidden from learners where possible
+
+If a future change threatens the single-route contract, treat that as a regression.

AGENT_RESTART_PROTOCOL.md

@@ -0,0 +1,32 @@
+# Agent Restart Protocol
+
+Session memory does not survive a restart. The reliable technique is:
+
+1. keep a repo-local context file
+2. tell the restarted agent exactly what to read first
+3. force it to inspect git state before it acts
+
+## Copy-Paste Prompt For QuantumLearning
+
+Use this when restarting an agent inside `QuantumLearning`:
+
+```text
+Read AGENT_CONTEXT.md first. Then read README.md, OPERATIONS.md, FIRST_RUN.md, configs/curriculum.toml, configs/mastery_blueprint.toml, and tests/test_course_flow.py. After that, inspect `git status --short --branch` and `git log --oneline -5`, summarize the current project state and constraints, and only then continue work.
+```
+
+## Copy-Paste Prompt For A New Coursework Repo
+
+Use this as the starting pattern for a new repo like `NTT-learning`:
+
+```text
+You are starting a new local-first Jupyter learning platform. Before building, inspect the repo state, create a repo-local `.venv`, and establish a single supported end-to-end walkthrough. The notebooks must distinguish clearly between META cells, MANDATORY cells, and FACULTATIVE cells. Difficulty 1-3 is reserved for mandatory cells; 4-10 is reserved for facultative cells. Hide plumbing where possible, keep the route unambiguous, and maintain repo-local operational scripts so a normal user can start, stop, restart, validate, and monitor the platform without agent help. After inspection, summarize the immediate setup plan and then execute it.
+```
+
+## Technique Summary
+
+The agent cannot truly "remember" across restarts unless the memory is written into the repo. The durable method is:
+
+- repo-local context file
+- repo-local operational docs
+- explicit restart prompt
+- git inspection before action

OPERATIONS.md

@@ -215,6 +215,15 @@ The clean transfer model is:
 
 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:

README.md

@@ -182,6 +182,7 @@ There is no second supported walkthrough.
 
 See [FIRST_RUN.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/FIRST_RUN.md) for the short startup checklist.
 See [OPERATIONS.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/OPERATIONS.md) for setup on another Mac, monitoring, validation, and recovery.
+See [AGENT_CONTEXT.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/AGENT_CONTEXT.md) and [AGENT_RESTART_PROTOCOL.md](/Users/oho/GitClone/CodexProjects/QuantumLearning/AGENT_RESTART_PROTOCOL.md) for fast agent restart handoff.
 
 The lower-level scripts still exist:
 - `scripts/bootstrap_mac.sh`