CI workflow, install/run scripts, and idiot-proof quick start

[StewAlexander-com]

Summary

Brings the project to a runnable, testable state with a one-command CI
pipeline and a two-command local setup.

CI (.github/workflows/ci.yml)

• Backend matrix: pytest on Python 3.10, 3.11, 3.12 against
  backend/requirements-dev.txt. All 89 tests pass locally.
• Frontend: node --check on every frontend/*.js; JSON parse
  check on frontend/**/*.json and curriculum/**/*.json.
• Scripts: shellcheck on install.sh / run.sh, then a
  full install + run smoke test that hits /api/health and / with
  TUTOR_SKIP_OLLAMA=1 so CI never needs an LLM.

Idiot-proof install (install.sh, run.sh)

• Two commands from git clone to a browser tab: ./install.sh then
  ./run.sh.
• install.sh is idempotent: reuses the venv, never installs system
  packages (Ollama in particular), prints the exact install command if
  Ollama is missing, and offers to pull gemma3:4b only when the
  Ollama daemon is already reachable.
• run.sh sets TUTOR_SERVE_FRONTEND=1 so the backend serves both the
  REST API and the static PWA on a single port (default 8001). The web
  UI loads even when Ollama is offline — chat replies return a clear
  503 instead of hanging.
• Env-var overrides for TUTOR_PORT, TUTOR_HOST, TUTOR_MODEL,
  TUTOR_SKIP_OLLAMA, TUTOR_SKIP_MODEL_PULL, TUTOR_NONINTERACTIVE.

Docs

• docs/install-runtime-workflow.md evaluates five candidate flows
  (manual / Docker / one-shot bootstrap / two scripts / Make) on
  steps, intervention, ease, and risk, and explains the chosen blend.
• README gains a Quick start section with troubleshooting and explicit
  behaviour when Ollama is not running.

Test plan

• cd backend && .venv/bin/pytest -q → 89 passed
• node --check frontend/*.js → all four files parse
• TUTOR_SKIP_OLLAMA=1 ./install.sh from clean state and from a
  reused venv → both succeed and are idempotent
• TUTOR_SKIP_OLLAMA=1 ./run.sh → backend reachable on the port;
  /api/health returns status: degraded, / returns the SPA
• ./scripts/smoke_run.sh → prints smoke ok

---

🤖 Generated by Computer