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

.github/workflows/ci.yml

@@ -0,0 +1,126 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  backend:
+    name: Backend tests (pytest)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: |
+            backend/requirements.txt
+            backend/requirements-dev.txt
+
+      - name: Install backend dependencies
+        working-directory: backend
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
+
+      - name: Run pytest
+        working-directory: backend
+        run: pytest -q
+
+  frontend:
+    name: Frontend JS syntax check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Syntax-check frontend JS
+        run: |
+          set -e
+          for f in frontend/*.js; do
+            echo "node --check $f"
+            node --check "$f"
+          done
+
+      - name: Validate JSON content
+        run: |
+          set -e
+          python3 -c "
+          import json, pathlib, sys
+          errors = 0
+          for p in list(pathlib.Path('frontend').rglob('*.json')) + list(pathlib.Path('curriculum').rglob('*.json')):
+              try:
+                  json.loads(p.read_text())
+                  print(f'ok  {p}')
+              except Exception as e:
+                  print(f'ERR {p}: {e}', file=sys.stderr)
+                  errors += 1
+          sys.exit(1 if errors else 0)
+          "
+
+  scripts:
+    name: Shell script lint + smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: shellcheck install/run scripts
+        run: |
+          if [ -f install.sh ] || [ -f run.sh ]; then
+            sudo apt-get update -y
+            sudo apt-get install -y shellcheck
+            for f in install.sh run.sh; do
+              [ -f "$f" ] && shellcheck -x "$f"
+            done
+          else
+            echo "no install.sh / run.sh yet; skipping"
+          fi
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Smoke-test install.sh (skip model pull, skip Ollama)
+        env:
+          TUTOR_SKIP_OLLAMA: "1"
+          TUTOR_SKIP_MODEL_PULL: "1"
+          TUTOR_NONINTERACTIVE: "1"
+        run: |
+          if [ -f install.sh ]; then
+            chmod +x install.sh run.sh scripts/smoke_run.sh
+            ./install.sh
+            test -d backend/.venv
+            backend/.venv/bin/python -c "import fastapi, uvicorn, httpx, pydantic"
+          else
+            echo "install.sh missing; skipping smoke test"
+          fi
+
+      - name: Smoke-test run.sh (no Ollama; check /api/health and /)
+        env:
+          TUTOR_SKIP_OLLAMA: "1"
+          TUTOR_PORT: "8801"
+        run: |
+          if [ -f scripts/smoke_run.sh ]; then
+            chmod +x scripts/smoke_run.sh
+            ./scripts/smoke_run.sh
+          else
+            echo "scripts/smoke_run.sh missing; skipping run.sh smoke"
+          fi

.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtualenvs
+.venv/
+backend/.venv/
+venv/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Logs / runtime
+/tmp/
+*.log

README.md

@@ -73,7 +73,61 @@ flowchart TD
     └── 0001-offline-first-local-llm.md
 ```
 
-## Running the Frontend
+## Quick start (idiot-proof)
+
+Two commands. macOS and Linux. Python 3.10+. Ollama is optional for a
+first look at the UI; required for chat replies and code evaluation.
+
+```bash
+gh repo clone StewAlexander-com/python-tutor
+cd python-tutor
+./install.sh        # creates venv, installs deps, pulls model if Ollama is up
+./run.sh            # serves UI + API on http://localhost:8001/
+```
+
+Then open <http://localhost:8001/> in your browser. You'll see the
+lesson list, the inline code lab (Run / Evaluate), and the floating
+"Ask tutor" chat panel.
+
+### Expected behaviour when Ollama is not running
+
+- The web UI loads normally — you can read lessons and run code locally
+  (`POST /api/run` does not need the LLM).
+- `/api/health` reports `status: "degraded"` and `ollama_reachable: false`.
+- `Evaluate` and the chat panel return a clear 503 — they don't hang.
+- As soon as you start `ollama serve`, everything works without a restart.
+
+### What if Ollama isn't installed?
+
+`install.sh` and `run.sh` **never** install system binaries on your
+behalf. If Ollama is missing, they print exactly what to run:
+
+```bash
+# macOS
+brew install ollama && ollama serve &
+
+# Linux
+curl -fsSL https://ollama.com/install.sh | sh && ollama serve &
+```
+
+Then `./install.sh` again to pull `gemma3:4b`.
+
+### Troubleshooting
+
+| Symptom                                | Fix                                                                                         |
+| -------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `Python 3.10+ is required`             | Install Python (see [`docs/install-runtime-workflow.md`](docs/install-runtime-workflow.md)) |
+| Chat returns `ollama_reachable: false` | Run `ollama serve` in another terminal                                                      |
+| Port 8001 already in use               | `TUTOR_PORT=9001 ./run.sh`                                                                  |
+| Model missing in chat replies          | `ollama pull gemma3:4b` (or set `TUTOR_MODEL` to your model)                                |
+| Service worker shows stale UI          | Hard-refresh the browser (Cmd/Ctrl-Shift-R)                                                 |
+| `install.sh` failed mid-`pip install`  | Re-run it — it's idempotent and reuses the venv                                             |
+
+For the design rationale behind the two-script flow (and the five flows
+we evaluated), see
+[`docs/install-runtime-workflow.md`](docs/install-runtime-workflow.md).
+
+## Running the Frontend (manual)
 
 A static, dependency-free SPA lives in [`frontend/`](frontend/). It was adapted from the [Python Power User](https://github.com/StewAlexander-com/Python-Power-User) project (MIT) and provides the learner-facing UI for this framework.