StewAlexander-com · StewAlexander-com · May 22, 2026 · May 22, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -75,6 +75,15 @@ jobs:
           sys.exit(1 if errors else 0)
           "
 
+      - name: Check hero landing site
+        run: |
+          if [ -f scripts/check_site.sh ]; then
+            chmod +x scripts/check_site.sh
+            ./scripts/check_site.sh
+          else
+            echo "scripts/check_site.sh missing; skipping"
+          fi
+
   scripts:
     name: Shell script lint + smoke
     runs-on: ubuntu-latest

diff --git a/README.md b/README.md
@@ -41,6 +41,24 @@ laptop.
 
 ---
 
+## Hero website
+
+A small static landing page lives at [`site/`](site/) — dark / amber
+aesthetic, the local-first loop in four steps, a simplified product
+mockup, and links straight to the two-command install. Useful for
+sharing the project without asking people to clone the repo first.
+
+```bash
+cd site
+python3 -m http.server 8080
+# open http://localhost:8080/
+```
+
+It's pure static HTML + CSS, no build step. See
+[`site/README.md`](site/README.md) for what's in it and the asset layout.
+
+---
+
 ## A quick look
 
 A 30-second tour of the UI, lab, and tutor. Click any image to enlarge.

diff --git a/scripts/check_site.sh b/scripts/check_site.sh
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# check_site.sh — light validity / asset checks for the hero landing page.
+#
+# Runs from repo root. Exits non-zero on the first failure, with a clear
+# message and an exit code that's safe for CI.
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SITE="$ROOT/site"
+HTML="$SITE/index.html"
+CSS="$SITE/style.css"
+
+fail() { echo "✗ $*" >&2; exit 1; }
+ok()   { echo "✓ $*"; }
+
+[ -f "$HTML" ] || fail "site/index.html missing"
+[ -f "$CSS" ]  || fail "site/style.css missing"
+ok "site/index.html and site/style.css present"
+
+# Required meta tags / sections — grep for substrings.
+need() {
+  grep -q -- "$1" "$HTML" || fail "site/index.html missing: $1"
+}
+need "<title>Python Tutor"
+need 'property="og:title"'
+need 'property="og:image"'
+need 'name="twitter:card"'
+need 'id="why"'
+need 'id="loop"'
+need 'id="screens"'
+need 'id="start"'
+ok "required <head> and section anchors present"
+
+# Every local href/src under site/ must resolve to a real file.
+# (We only check ./relative paths — external URLs are skipped.)
+python3 - "$HTML" "$SITE" <<'PY'
+import re, sys, os
+html_path, site_dir = sys.argv[1], sys.argv[2]
+src = open(html_path, encoding="utf-8").read()
+refs = re.findall(r'(?:href|src)\s*=\s*"(\./[^"]+)"', src)
+missing = []
+for r in refs:
+    rel = r[2:]  # drop "./"
+    rel = rel.split("#", 1)[0].split("?", 1)[0]
+    p = os.path.join(site_dir, rel)
+    if not os.path.exists(p):
+        missing.append(r)
+if missing:
+    print("✗ missing local assets:", file=sys.stderr)
+    for m in missing:
+        print("    " + m, file=sys.stderr)
+    sys.exit(1)
+print(f"✓ all {len(refs)} local references resolve")
+PY
+
+# Should NOT contain hard-coded localhost links (would break in prod).
+if grep -nE 'href="http://localhost' "$HTML" >/dev/null; then
+    fail "site/index.html contains hard-coded http://localhost hrefs"
+fi
+ok "no hard-coded localhost hrefs"
+
+# Cheap structural sanity check: balanced <main> tag.
+opens=$(grep -c '<main' "$HTML" || true)
+closes=$(grep -c '</main>' "$HTML" || true)
+[ "$opens" = "$closes" ] || fail "unbalanced <main> tags ($opens open, $closes close)"
+ok "<main> tags balanced"
+
+echo "site checks passed"
diff --git a/site/README.md b/site/README.md
@@ -0,0 +1,48 @@
+# Hero website
+
+A small static landing page for Python Tutor. It mirrors the app's
+dark / amber aesthetic and explains the local-first loop without
+needing to launch the backend.
+
+## Files
+
+```
+site/
+├── index.html                 # the landing page
+├── style.css                  # design tokens mirror frontend/base.css
+└── assets/
+    ├── favicon.svg
+    ├── og-image.png           # 1200×630 social card (reused from frontend)
+    └── screenshots/           # six UI screenshots, lazy-loaded
+```
+
+## Preview locally
+
+The page is pure static HTML + CSS — no build step.
+
+```bash
+cd site
+python3 -m http.server 8080
+# open http://localhost:8080/
+```
+
+Or open `site/index.html` directly in a browser (file://) — all asset
+paths are relative.
+
+## Why a separate landing
+
+The app at `frontend/` is a PWA: lesson browser, code lab, tutor chat.
+It assumes the FastAPI backend on `:8001`. The landing page is for
+**people who haven't installed anything yet** — a credible 30-second
+overview that points them at the repo and the two-command install.
+
+## Checks
+
+`scripts/check_site.sh` runs from the repo root and verifies:
+
+- referenced screenshots and OG image exist on disk
+- `<title>` and Open Graph tags are present
+- no `localhost:` URLs are baked into hrefs/srcs
+- key sections (`#why`, `#loop`, `#screens`, `#start`) are wired up
+
+CI invokes the same script.
diff --git a/site/assets/favicon.svg b/site/assets/favicon.svg
diff --git a/site/assets/og-image.png b/site/assets/og-image.png
diff --git a/site/assets/screenshots/01-home.png b/site/assets/screenshots/01-home.png
diff --git a/site/assets/screenshots/02-lesson-browser.png b/site/assets/screenshots/02-lesson-browser.png
diff --git a/site/assets/screenshots/03-section-view.png b/site/assets/screenshots/03-section-view.png
diff --git a/site/assets/screenshots/04-code-lab-run.png b/site/assets/screenshots/04-code-lab-run.png
diff --git a/site/assets/screenshots/05-evaluate-feedback.png b/site/assets/screenshots/05-evaluate-feedback.png
diff --git a/site/assets/screenshots/06-tutor-chat.png b/site/assets/screenshots/06-tutor-chat.png