fix(ui): browser-playable overlay video (H.264) + light all dropdown option lists

.gitattributes

@@ -35,3 +35,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 docs/FormScout-FMS-Spec.md.pdf filter=lfs diff=lfs merge=lfs -text
 docs/plans/FormScout-Build-Prompt.md.pdf filter=lfs diff=lfs merge=lfs -text
+assets/screenings/*.png filter=lfs diff=lfs merge=lfs -text

CLAUDE.md

@@ -170,7 +170,7 @@ Track the running sum in `MODEL_BUDGET.md`. The two Qwen3-VL-8B models share a b
 
 The UI uses **Gradio `gr.Blocks`** with custom CSS/theme (`formscout/ui/theme.py`). Custom Svelte components for score dial, asymmetry bars, rubric drawer are planned for Phase 4. Use `gradio-svelte-expert` agent for Svelte component work.
 
-- ZeroGPU: wrap heavy inference (`Pose2DAgent.run`, `Body3DAgent.run`) in `@spaces.GPU` before deploying to Spaces.
+- ZeroGPU: `app.py`'s `process_video` (the Start Analysis handler) is decorated with `@spaces.GPU` (via the `gpu_task` shim, no-op off-Space) so one GPU window wraps the whole pipeline — pose, optional 3D, and the judge. **ZeroGPU aborts startup with "No @spaces.GPU function detected" unless a decorated function exists at import time**, so the decorator must stay at module level on a top-level function, not buried behind a lazy import. Window length is `config.ZEROGPU_DURATION` (default 120s, `FORMSCOUT_ZEROGPU_DURATION`).
 - Verify Gradio APIs against current docs before use — pin exact versions in `requirements.txt`.
 
 ## Build phases

app.py

@@ -20,6 +20,23 @@ from formscout import config
 from formscout import session as session_mod
 from formscout.startup import ensure_checkpoints
 
+# ─── ZeroGPU ──────────────────────────────────────────────────────────────────
+# On an HF Spaces ZeroGPU runtime the heavy analysis MUST run inside an
+# @spaces.GPU function, and that function must already exist at import time:
+# ZeroGPU scans for one during startup and aborts the Space with
+# "No @spaces.GPU function detected during startup" if none is registered.
+# We decorate process_video (the Start Analysis handler) so a single GPU window
+# covers the whole pipeline — pose, optional 3D, and the Qwen3-VL judge. Off a
+# ZeroGPU Space the `spaces` package is absent (or its decorator is effect-free),
+# so local runs and CPU Spaces are unaffected.
+try:
+    import spaces
+
+    gpu_task = spaces.GPU(duration=config.ZEROGPU_DURATION)
+except Exception:  # local dev / non-ZeroGPU — decorate as a no-op
+    def gpu_task(fn):
+        return fn
+
 ensure_checkpoints()
 
 
@@ -47,12 +64,39 @@ SCORE_DESCRIPTIONS = {
     0: "Pain reported — clinician referral required",
 }
 
+# Per-test illustration shown as a movement guide (test_key -> filename).
+_ASSET_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "assets", "screenings")
+SCREENING_ASSETS = {
+    "deep_squat": "deep-squat.png",
+    "hurdle_step": "hurdle-step.png",
+    "inline_lunge": "inline-lunge.png",
+    "shoulder_mobility": "shoulder-mobility.png",
+    "active_slr": "active-straight-leg-raise.png",
+    "trunk_stability_pushup": "trunk-stability-push-up.png",
+    "rotary_stability": "rotary-stability.png",
+}
+
+
+def _screening_image(test_display_name: str) -> str | None:
+    """Resolve the movement-guide image path for a dropdown display name."""
+    key = {name: val for name, val in FMS_TESTS}.get(test_display_name)
+    fname = SCREENING_ASSETS.get(key)
+    if not fname:
+        return None
+    path = os.path.join(_ASSET_DIR, fname)
+    return path if os.path.exists(path) else None
+
 
 # ─── Processing ──────────────────────────────────────────────────────────────
 
+@gpu_task
 def process_video(video_path: str, test_name: str, side: str, model_key: str,
                   layers: list[str], session_state):
-    """Analyse one clip and accumulate it into the screening session."""
+    """Analyse one clip and accumulate it into the screening session.
+
+    Decorated with @spaces.GPU on ZeroGPU: the whole pipeline (pose, optional 3D,
+    Qwen3-VL judge) runs inside one GPU window. The decorator is a no-op off-Space.
+    """
     if not video_path:
         return (
             session_state, _render_empty_state(), "Upload a video to begin analysis.",
@@ -277,11 +321,11 @@ def _finish_session(session_state):
     """Build the composite report + PDF for the whole session."""
     if not session_state or not session_state.entries:
         return ("⚠️ No clips analysed yet — analyse at least one clip first.",
-                None, None)
+                None, None, None)
 
     report, pdf_path = session_mod.finish_session(session_state)
     if report is None:
-        return ("⚠️ Nothing to report.", None, None)
+        return ("⚠️ Nothing to report.", None, None, None)
 
     if report.composite is not None:
         summary = [f"## Composite: {report.composite} / 21"]
@@ -304,7 +348,7 @@ def _finish_session(session_state):
 
     md_path = os.path.join(session_state.session_dir, "analysis.md")
     md_out = md_path if os.path.exists(md_path) else None
-    return "\n".join(summary), pdf_path, md_out
+    return "\n".join(summary), pdf_path, md_out, report.scoresheet_path
 
 
 # ─── App Builder ─────────────────────────────────────────────────────────────
@@ -348,6 +392,15 @@ def build_app() -> gr.Blocks:
                         scale=1,
                     )
 
+                movement_guide = gr.Image(
+                    value=_screening_image("Deep Squat"),
+                    label="Movement guide",
+                    interactive=False,
+                    buttons=[],  # no download/share/fullscreen overlay
+                    height=240,
+                    elem_id="movement-guide",
+                )
+
                 _available_models = config.available_pose_models() or config.POSE_MODELS
                 _default_model = (
                     config.DEFAULT_POSE_MODEL
@@ -407,7 +460,8 @@ def build_app() -> gr.Blocks:
                     with gr.TabItem("🗂️ Session"):
                         session_table = gr.Markdown("*No clips analysed yet.*")
                         finish_summary = gr.Markdown("")
-                        pdf_file = gr.File(label="Screening Report (PDF)", visible=True)
+                        scoresheet_file = gr.File(label="FMS Scoring Sheet (PDF)", visible=True)
+                        pdf_file = gr.File(label="Detailed Screening Report (PDF)", visible=True)
                         md_file = gr.File(label="Analysis Log (Markdown)", visible=True)
 
         # Footer safety banner
@@ -429,6 +483,11 @@ def build_app() -> gr.Blocks:
             side = {"N/A": "na", "Left": "left", "Right": "right"}.get(side_display, "na")
             return process_video(video, test_name, side, pose_model_key, overlay_layers, sess)
 
+        # Swap the movement-guide illustration when the selected test changes.
+        test_dropdown.change(
+            fn=_screening_image, inputs=[test_dropdown], outputs=[movement_guide],
+        )
+
         submit_btn.click(
             fn=_map_inputs,
             inputs=[video_input, test_dropdown, side_dropdown, pose_model_dropdown,
@@ -450,7 +509,7 @@ def build_app() -> gr.Blocks:
         finish_btn.click(
             fn=_finish_session,
             inputs=[session_state],
-            outputs=[finish_summary, pdf_file, md_file],
+            outputs=[finish_summary, pdf_file, md_file, scoresheet_file],
         )
 
     return app
@@ -458,4 +517,5 @@ def build_app() -> gr.Blocks:
 
 if __name__ == "__main__":
     app = build_app()
-    app.launch(theme=formscout_theme(), css=FORMSCOUT_CSS)
+    app.launch(theme=formscout_theme(), css=FORMSCOUT_CSS,
+               allowed_paths=[_ASSET_DIR])

formscout/agents/prompts/c2_judge.md

@@ -14,13 +14,14 @@ FMS scoring scale (apply per side; the test score is the LOWER side):
 - 1: the person cannot perform the movement pattern even with the allowed regression.
 - 0: PAIN. You CANNOT see pain. Never assign 0 yourself.
 
-Per-test criteria to weigh (use the features as primary evidence):
-- deep_squat (3): femur below horizontal, torso roughly parallel to the tibia, knees tracking over the feet, dowel staying aligned over the feet, heels flat. (2): the same achieved only with heels elevated. (1): criteria unmet even with heels elevated.
-- hurdle_step / inline_lunge: minimal sway/loss of balance, knee/hip/ankle alignment maintained, no contact with the hurdle, dowel/posture stable. Compensation -> 2; failure to complete -> 1. Report L/R asymmetry.
-- shoulder_mobility: judge by the normalized inter-fist distance bands (per side). Report asymmetry.
-- active_slr: judge the raised-leg hip-flexion angle relative to the standard band; the down leg stays flat.
-- trunk_stability_pushup: the body must move as one rigid unit (low segment-angle variance through the press); sag/lag or needing the easier hand position -> 2.
-- rotary_stability: smooth contralateral (or the allowed unilateral) coordination with a stable trunk; loss of coordination/balance -> lower.
+Per-test criteria to weigh (official FMS grading; use the features as primary evidence):
+- deep_squat. (3): upper torso parallel with the tibia or toward vertical, femur below horizontal, knees aligned over the feet, dowel aligned over the feet, heels flat. (2): all of the above achieved only with the heels elevated (on a board). (1): tibia and torso not parallel, femur not below horizontal, knees not aligned over the feet, or lumbar flexion noted.
+- hurdle_step (bilateral, score each side). (3): hips/knees/ankles stay aligned in the sagittal plane, minimal lumbar-spine movement, dowel and hurdle remain parallel. (2): alignment lost between hips/knees/ankles, lumbar movement, or dowel and hurdle not parallel. (1): contact between foot and hurdle (cord not cleared) or any loss of balance. Report L/R asymmetry.
+- inline_lunge (bilateral, score each side). (3): minimal-to-no torso movement, feet remain in the sagittal plane of the board, dowel stays vertical and in contact, rear knee touches behind the heel of the front foot. (2): torso movement, feet/dowel leave the sagittal plane, or rear knee does not touch behind the front heel. (1): loss of balance (steps off the board) or inability to complete the pattern. Report L/R asymmetry.
+- shoulder_mobility (bilateral, score each side). (3): fists within one hand length. (2): fists within one-and-a-half hand lengths. (1): fists greater than one-and-a-half hand lengths apart. Judge by the normalized inter-fist distance bands; report asymmetry.
+- active_slr (bilateral, score each side). (3): the raised-ankle malleolus reaches between mid-thigh and the ASIS of the down leg. (2): the malleolus reaches between mid-thigh and the joint line/mid-patella. (1): the malleolus stays below the joint line. The non-moving (down) limb stays flat in neutral. Judge by the raised-leg hip-flexion angle relative to the standard band.
+- trunk_stability_pushup. The body must lift as one rigid unit with no lag/sag in the spine (low segment-angle variance through the press). (3): one clean rep from the hardest start hand position (men: thumbs at forehead; women: thumbs at chin). (2): one clean rep only from the easier position (men: chin; women: clavicle). (1): unable to perform a rep even from the easier position. If sex is unknown, judge primarily on the rigid-unit press and note the assumption.
+- rotary_stability (score each side). (3): a correct UNILATERAL (same-side) rep — same-side elbow and knee touch over the board without touching down, trunk parallel to the board. (2): a correct DIAGONAL (contralateral, opposite elbow/knee) rep over the board. (1): inability to perform a diagonal repetition. Note: a clean unilateral rep outranks a diagonal one.
 
 Hard safety rules:
 - If there is any clearing-test context, visible pain, grimacing, or an aborted rep, set needs_human=true and score=null. Do not score it.

formscout/agents/scoresheet.py

@@ -0,0 +1,176 @@
+"""
+ScoreSheetAgent — renders a one-page FMS scoring sheet from a ReportResult.
+
+A FormScout-styled scorecard (NOT a reproduction of the copyrighted FMS chart):
+all seven screens in their canonical order, each with its 0–3 score, L/R columns
+for the bilateral tests, the composite out of 21, and the standard FMS risk
+interpretation (>=14 reduced injury risk; <=13 increased risk). It is the
+single-page companion download to the detailed PdfReportAgent report.
+
+Input:  ReportResult, session_dir (str), optional meta dict (name/date/etc.)
+Output: path to the written PDF (str), or None on failure (e.g. reportlab missing).
+Failure: returns None, never raises.
+Params: 0 (pure rendering — no model).
+License: n/a.
+Gated: no.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import logging
+import os
+
+from formscout.types import ReportResult
+
+logger = logging.getLogger(__name__)
+
+DISCLAIMER = "Screening aid — not a diagnosis. Pain or clearing tests require a clinician."
+
+# Canonical FMS order; (key, display label, is_bilateral). Post-MVP additions
+# (clearing tests, adjunct measures) slot in here without touching the renderer.
+CANONICAL_TESTS = [
+    ("deep_squat", "1. Deep Squat", False),
+    ("hurdle_step", "2. Hurdle Step", True),
+    ("inline_lunge", "3. In-Line Lunge", True),
+    ("shoulder_mobility", "4. Shoulder Mobility", True),
+    ("active_slr", "5. Active Straight-Leg Raise", True),
+    ("trunk_stability_pushup", "6. Trunk Stability Push-Up", False),
+    ("rotary_stability", "7. Rotary Stability", False),
+]
+
+
+def _cell(score, needs_human: bool) -> str:
+    """Render one score cell: a number, a review flag, or a blank placeholder."""
+    if needs_human:
+        return "Review"
+    if score is None:
+        return "—"
+    return str(score)
+
+
+class ScoreSheetAgent:
+    """Assembles the single-page FMS scoring sheet via ReportLab."""
+
+    def run(self, report: ReportResult, session_dir: str,
+            meta: dict | None = None) -> str | None:
+        try:
+            from reportlab.lib import colors
+            from reportlab.lib.pagesizes import LETTER
+            from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
+            from reportlab.lib.units import inch
+            from reportlab.platypus import (
+                Paragraph, SimpleDocTemplate, Spacer, Table, TableStyle,
+            )
+        except Exception as e:
+            logger.warning("reportlab unavailable: %s", e)
+            return None
+
+        out_path = os.path.join(session_dir, "formscout_fms_scoresheet.pdf")
+        try:
+            styles = getSampleStyleSheet()
+            ink = colors.HexColor("#243a34")
+            banner = ParagraphStyle(
+                "banner", parent=styles["Normal"], fontSize=9, textColor=colors.white,
+                backColor=colors.HexColor("#cf922a"), alignment=1, borderPadding=6,
+                spaceAfter=12,
+            )
+            small = ParagraphStyle("small", parent=styles["Normal"], fontSize=8,
+                                   textColor=ink)
+
+            # Index report data by test name.
+            by_test = {t["test_name"]: t for t in (report.per_test or [])}
+            asym = {a["test"]: a for a in (report.asymmetries or [])}
+
+            story = []
+            story.append(Paragraph(f"<b>&#9888; {DISCLAIMER}</b>", banner))
+            story.append(Paragraph("FormScout — FMS Scoring Sheet", styles["Title"]))
+
+            # Optional athlete/meta header (auto-filled date by default).
+            meta = dict(meta or {})
+            meta.setdefault("date", _dt.date.today().isoformat())
+            meta_bits = [f"<b>{k.title()}:</b> {v}" for k, v in meta.items() if v]
+            if meta_bits:
+                story.append(Paragraph(" &nbsp;&nbsp; ".join(meta_bits), small))
+            story.append(Spacer(1, 0.15 * inch))
+
+            # Scores table: # / Test, Left, Right, Score, Status.
+            header = ["Test", "Left", "Right", "Score", "Status"]
+            rows = [header]
+            for key, label, bilateral in CANONICAL_TESTS:
+                t = by_test.get(key)
+                needs_human = bool(t and t.get("needs_human"))
+                score = t.get("score") if t else None
+                if not t:
+                    status = "Not screened"
+                elif needs_human:
+                    status = "Clinician review"
+                elif score is None:
+                    status = "Unscored"
+                else:
+                    status = "Scored"
+
+                if bilateral and key in asym:
+                    left = _cell(asym[key]["left_score"], needs_human)
+                    right = _cell(asym[key]["right_score"], needs_human)
+                elif bilateral:
+                    # Only one side (or none) was screened — no asymmetry pair.
+                    left = right = _cell(score, needs_human) if t else "—"
+                else:
+                    left = right = ""  # n/a for non-bilateral tests
+                rows.append([label, left, right, _cell(score, needs_human), status])
+
+            comp = (f"{report.composite}" if report.composite is not None else "—")
+            rows.append(["Total Score (Tests 1–7)", "", "", f"{comp} / 21",
+                         "Complete" if report.composite is not None else "Incomplete"])
+
+            tbl = Table(rows, colWidths=[3.0 * inch, 0.8 * inch, 0.8 * inch,
+                                         0.9 * inch, 1.4 * inch])
+            tbl.setStyle(TableStyle([
+                ("FONTSIZE", (0, 0), (-1, -1), 9),
+                ("TEXTCOLOR", (0, 0), (-1, -1), ink),
+                ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#1f6e6e")),
+                ("TEXTCOLOR", (0, 0), (-1, 0), colors.white),
+                ("BACKGROUND", (0, -1), (-1, -1), colors.HexColor("#f7eedd")),
+                ("FONTNAME", (0, -1), (-1, -1), "Helvetica-Bold"),
+                ("ALIGN", (1, 0), (-1, -1), "CENTER"),
+                ("GRID", (0, 0), (-1, -1), 0.5, colors.HexColor("#c9d6cf")),
+                ("ROWBACKGROUNDS", (0, 1), (-1, -2),
+                 [colors.white, colors.HexColor("#f3f7f5")]),
+                ("TOPPADDING", (0, 0), (-1, -1), 5),
+                ("BOTTOMPADDING", (0, 0), (-1, -1), 5),
+            ]))
+            story.append(tbl)
+            story.append(Spacer(1, 0.18 * inch))
+
+            # Risk interpretation — only meaningful when the screen is complete.
+            if report.composite is not None:
+                if report.composite >= 14:
+                    risk = (f"Composite {report.composite}/21 &#8805; 14 — associated in the "
+                            "FMS literature with <b>reduced</b> injury risk during physical "
+                            "activity.")
+                else:
+                    risk = (f"Composite {report.composite}/21 &#8804; 13 — associated in the "
+                            "FMS literature with <b>increased</b> injury risk during physical "
+                            "activity.")
+            else:
+                risk = ("Composite is incomplete — all seven screens must be scored before the "
+                        "14-point risk threshold applies.")
+            story.append(Paragraph(risk, small))
+
+            if report.asymmetries:
+                story.append(Spacer(1, 0.1 * inch))
+                bits = ", ".join(
+                    f"{a['test'].replace('_', ' ').title()} (L{a['left_score']}/R{a['right_score']},"
+                    f" &#916;{a['delta']})" for a in report.asymmetries)
+                story.append(Paragraph(f"<b>Left/right asymmetries:</b> {bits}", small))
+
+            story.append(Spacer(1, 0.25 * inch))
+            story.append(Paragraph(f"<b>&#9888; {DISCLAIMER}</b>", banner))
+
+            doc = SimpleDocTemplate(out_path, pagesize=LETTER,
+                                    topMargin=0.6 * inch, bottomMargin=0.6 * inch)
+            doc.build(story)
+            return out_path
+        except Exception as e:
+            logger.warning("scoresheet build failed: %s", e)
+            return None

formscout/agents/visualizer.py

@@ -268,17 +268,21 @@ class PoseVisualizer:
 
             scaled_keypoints = [_scale_kps(k) for k in pose2d.keypoints]
 
-            # Write raw mp4v to a temp file, then remux with ffmpeg faststart
-            import subprocess
-            import tempfile as _tf
-            tmp = _tf.NamedTemporaryFile(suffix="_raw.mp4", delete=False)
-            tmp_path = tmp.name
-            tmp.close()
-
-            fourcc = cv2.VideoWriter_fourcc(*"mp4v")
-            writer = cv2.VideoWriter(tmp_path, fourcc, fps, (out_w, out_h))
-            if not writer.isOpened():
-                logger.warning("VideoWriter failed to open: %s", tmp_path)
+            # Prefer H.264 (avc1): browser-playable via OpenCV's bundled FFmpeg, no
+            # external ffmpeg needed. Fall back to mp4v only if avc1 can't open
+            # (older OpenCV builds) — that case is transcoded after the write.
+            writer = None
+            used_fourcc = None
+            for _tag in ("avc1", "mp4v"):
+                candidate = cv2.VideoWriter(
+                    output_path, cv2.VideoWriter_fourcc(*_tag), fps, (out_w, out_h)
+                )
+                if candidate.isOpened():
+                    writer, used_fourcc = candidate, _tag
+                    break
+                candidate.release()
+            if writer is None:
+                logger.warning("VideoWriter failed to open: %s", output_path)
                 return None
 
             trail_history: dict[int, deque] = {j: deque(maxlen=TRAIL_LENGTH) for j in range(17)}
@@ -309,19 +313,29 @@ class PoseVisualizer:
 
             writer.release()
 
-            # Remux with faststart so browsers can seek without downloading the whole file
-            try:
-                subprocess.run(
-                    ["ffmpeg", "-y", "-i", tmp_path, "-c", "copy",
-                     "-movflags", "+faststart", output_path],
-                    check=True, capture_output=True,
-                )
+            # mp4v is NOT browser-playable; if we had to fall back to it, transcode
+            # to H.264 with ffmpeg when available (best effort).
+            if used_fourcc != "avc1":
                 import os
-                os.unlink(tmp_path)
-            except Exception as ffmpeg_err:
-                logger.warning("ffmpeg remux failed (%s) — using raw mp4v", ffmpeg_err)
                 import shutil
-                shutil.move(tmp_path, output_path)
+                import subprocess
+                if shutil.which("ffmpeg"):
+                    raw = output_path + ".raw.mp4"
+                    try:
+                        os.replace(output_path, raw)
+                        subprocess.run(
+                            ["ffmpeg", "-y", "-i", raw, "-c:v", "libx264",
+                             "-pix_fmt", "yuv420p", "-movflags", "+faststart", output_path],
+                            check=True, capture_output=True,
+                        )
+                        os.unlink(raw)
+                    except Exception as e:
+                        logger.warning("ffmpeg transcode failed (%s) — leaving mp4v", e)
+                        if os.path.exists(raw):
+                            os.replace(raw, output_path)
+                else:
+                    logger.warning("wrote mp4v but no avc1/ffmpeg — overlay may not "
+                                   "play in-browser")
 
             return output_path
 

formscout/config.py

@@ -147,14 +147,40 @@ LLAMA_CPP_PORT_EMBED = 8081
 # ─── Judge backend selection ────────────────────────────────────────────────
 # "llama_cpp"   — local llama-server (default for local dev; works perfectly)
 # "transformers"— in-process Qwen3-VL via transformers, GPU on HF Spaces (ZeroGPU)
-# "auto"        — transformers on a Space (SPACE_ID set), llama_cpp locally
+# "auto"        — transformers ONLY on a GPU/ZeroGPU Space, else llama_cpp
 JUDGE_BACKEND = os.environ.get("FORMSCOUT_JUDGE_BACKEND", "auto")
 JUDGE_HF_MODEL = os.environ.get("FORMSCOUT_JUDGE_HF_MODEL", "Qwen/Qwen3-VL-8B-Instruct")
 ON_HF_SPACE = bool(os.environ.get("SPACE_ID"))
 
+# Seconds the ZeroGPU window stays allocated per analysis. One window wraps the
+# whole pipeline (pose, optional 3D, Qwen3-VL judge), so size it for the slowest
+# clip; raise via env for long videos. Only effective on a ZeroGPU Space.
+ZEROGPU_DURATION = int(os.environ.get("FORMSCOUT_ZEROGPU_DURATION", "120"))
+
+
+def has_gpu() -> bool:
+    """True on a ZeroGPU Space (env flag) or when CUDA is actually present.
+
+    ZeroGPU exposes no CUDA outside @spaces.GPU, so it is detected via the
+    SPACES_ZERO_GPU env flag; ordinary GPU Spaces report via torch.cuda.
+    """
+    if os.environ.get("SPACES_ZERO_GPU") or os.environ.get("ZERO_GPU"):
+        return True
+    try:
+        import torch
+        return bool(torch.cuda.is_available())
+    except Exception:
+        return False
+
 
 def resolve_judge_backend() -> str:
-    """Resolve the effective judge backend from JUDGE_BACKEND + environment."""
+    """Resolve the effective judge backend from JUDGE_BACKEND + environment.
+
+    `auto` only engages the heavy in-process transformers model when a GPU is
+    actually available — a CPU-only Space stays on llama_cpp (which is then
+    unreachable, so the Judge falls back to the fast rubric instead of trying to
+    run a 17 GB model on CPU).
+    """
     if JUDGE_BACKEND in ("llama_cpp", "transformers"):
         return JUDGE_BACKEND
-    return "transformers" if ON_HF_SPACE else "llama_cpp"
+    return "transformers" if (ON_HF_SPACE and has_gpu()) else "llama_cpp"

formscout/serving/transformers_vlm.py

@@ -39,19 +39,27 @@ except Exception:  # pragma: no cover
         return fn
 
 
-@_gpu
-def _generate(model_id: str, prompt: str, pil_images: list, max_tokens: int,
-              temperature: float) -> str:  # pragma: no cover - needs GPU + model
-    """Load (cached) and run Qwen3-VL; returns the raw decoded string."""
-    import torch
-    from transformers import AutoModelForImageTextToText, AutoProcessor
-
+def _ensure_loaded(model_id: str):  # pragma: no cover - downloads ~16 GB
+    """Load processor + model to CPU once (cached). Kept OUT of the GPU window so
+    the 17 GB download/load does not eat ZeroGPU time."""
     if "model" not in _CACHE:
+        import torch
+        from transformers import AutoModelForImageTextToText, AutoProcessor
         _CACHE["processor"] = AutoProcessor.from_pretrained(model_id)
         _CACHE["model"] = AutoModelForImageTextToText.from_pretrained(
-            model_id, torch_dtype="auto", device_map="auto",
+            model_id, torch_dtype=torch.bfloat16,
         )
+    return _CACHE["processor"], _CACHE["model"]
+
+
+@_gpu
+def _generate(prompt: str, pil_images: list, max_tokens: int,
+              temperature: float) -> str:  # pragma: no cover - needs GPU + model
+    """Move the cached model to CUDA and run Qwen3-VL (ZeroGPU window)."""
+    import torch
+
     processor, model = _CACHE["processor"], _CACHE["model"]
+    model.to("cuda")
 
     content = [{"type": "image", "image": im} for im in pil_images]
     content.append({"type": "text", "text": prompt})
@@ -60,7 +68,7 @@ def _generate(model_id: str, prompt: str, pil_images: list, max_tokens: int,
     inputs = processor.apply_chat_template(
         messages, tokenize=True, add_generation_prompt=True,
         return_tensors="pt", return_dict=True,
-    ).to(model.device)
+    ).to("cuda")
 
     with torch.no_grad():
         out = model.generate(
@@ -90,7 +98,8 @@ class TransformersVLMClient:
                  stop: list[str] | None = None) -> dict:
         try:
             pil_images = self._decode_images(images)
-            text = _generate(self.model_id, prompt, pil_images, max_tokens, temperature)
+            _ensure_loaded(self.model_id)  # CPU load (no GPU time)
+            text = _generate(prompt, pil_images, max_tokens, temperature)
             return LlamaCppClient._parse_json_reply(text)
         except Exception as e:  # pragma: no cover - needs GPU + model
             logger.warning("transformers VLM failed (%s) — falling back to rubric", e)

formscout/session.py

@@ -179,7 +179,14 @@ def finish_session(session) -> tuple[ReportResult | None, str | None]:
     except Exception as e:
         logger.warning("pdf generation failed: %s", e)
 
-    report = replace(report, pdf_path=pdf_path)
+    scoresheet_path = None
+    try:
+        from formscout.agents.scoresheet import ScoreSheetAgent
+        scoresheet_path = ScoreSheetAgent().run(report, session.session_dir)
+    except Exception as e:
+        logger.warning("scoresheet generation failed: %s", e)
+
+    report = replace(report, pdf_path=pdf_path, scoresheet_path=scoresheet_path)
     return report, pdf_path
 
 

formscout/types.py

@@ -6,7 +6,6 @@ Validate at every boundary — never accept raw dicts across agent boundaries.
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any
 
 
 @dataclass(frozen=True)
@@ -139,6 +138,7 @@ class ReportResult:
     pdf_path: str | None
     low_confidence_flags: list
     disagreement_flags: list
+    scoresheet_path: str | None = None  # one-page FMS scoring sheet (separate download)
     notes: str = ""
 
 

formscout/ui/theme.py

@@ -16,6 +16,8 @@ SAGE_DEEP = "#9cbcad"
 TEAL = "#2b8a8a"
 TEAL_HOVER = "#1f6e6e"
 TEAL_DEEP = "#175757"
+TEAL_LIGHT = "#d6ecec"
+TEAL_LIGHT_HOVER = "#bfe3e3"
 GOLD = "#e0a43b"
 GOLD_DEEP = "#cf922a"
 INK = "#243a34"
@@ -59,15 +61,20 @@ def formscout_theme() -> gr.Theme:
         button_secondary_background_fill="rgba(156, 188, 173, 0.55)",
         button_secondary_text_color=INK,
         # Inputs
-        input_background_fill="rgba(255, 255, 255, 0.85)",
-        input_background_fill_dark="rgba(255, 255, 255, 0.85)",
+        input_background_fill="rgba(255, 255, 255, 0.92)",
+        input_background_fill_dark="rgba(255, 255, 255, 0.92)",
+        input_background_fill_focus="rgba(255, 255, 255, 1.0)",
         input_border_color="rgba(43, 138, 138, 0.30)",
         input_border_color_focus="rgba(43, 138, 138, 0.75)",
+        # Labels — pin light in both modes so no dark dropdown header appears
+        block_label_background_fill="rgba(188, 211, 200, 0.55)",
+        block_label_background_fill_dark="rgba(188, 211, 200, 0.55)",
+        block_label_text_color=INK,
+        block_label_text_color_dark=INK,
         # Text
         body_text_color=INK,
         body_text_color_dark=INK,
         block_title_text_color=TEAL_DEEP,
-        block_label_text_color=INK_MUTED,
         # Spacing
         block_padding="16px",
         layout_gap="16px",
@@ -111,6 +118,32 @@ FORMSCOUT_CSS = f"""
     color: {GOLD_DEEP};
 }}
 
+/* Dropdown option lists — pin light-teal cells in both modes (Gradio's default
+   --background-fill-primary resolves dark here, same issue as the labels). */
+.gradio-container ul.options {{
+    background: {TEAL_LIGHT} !important;
+    border: 1px solid rgba(43, 138, 138, 0.30) !important;
+}}
+.gradio-container ul.options li.item {{
+    background: {TEAL_LIGHT} !important;
+    color: {INK} !important;
+}}
+.gradio-container ul.options li.item:hover,
+.gradio-container ul.options li.item.active {{
+    background: {TEAL_LIGHT_HOVER} !important;
+    color: {INK} !important;
+}}
+
+/* Movement-guide illustration — rounded card matching the test selection */
+#movement-guide img {{
+    border-radius: 12px;
+    object-fit: contain;
+}}
+#movement-guide {{
+    border: 1px solid rgba(43, 138, 138, 0.22);
+    border-radius: 14px;
+}}
+
 /* Score display */
 .score-card {{
     background: rgba(43, 138, 138, 0.08);

scripts/hf_upload.sh

@@ -21,8 +21,11 @@ set -euo pipefail
 
 cd "$(dirname "$0")/.."
 
-MODEL_REPO="silas-therapy/small-functional-movement-screening"
-SPACE_REPO="spaces/silas-therapy/small-functional-movement-screening"
+REPO_NAME="small-functional-movement-screening"
+BLADE_OWNER="${FORMSCOUT_HF_BLADE_OWNER:-BladeSzaSza}"
+MODEL_REPO="silas-therapy/$REPO_NAME"
+SPACE_REPO="spaces/silas-therapy/$REPO_NAME"
+SPACE_BLADESZASZA_REPO="spaces/$BLADE_OWNER/$REPO_NAME"
 MSG="${1:-$(git log -1 --pretty=%s)}"
 LARGE_THRESHOLD="${FORMSCOUT_HF_LARGE_THRESHOLD:-500}"
 
@@ -76,22 +79,62 @@ if (( N_FILES == 0 )); then
     exit 1
 fi
 
+# upload_repo <repo> [pr|direct]
+#   pr     — open a PR (shared org repos; review before merge)
+#   direct — commit straight to main (repos you own; deploys immediately)
 upload_repo() {
     local repo="$1"
+    local mode="${2:-pr}"
     if (( N_FILES > LARGE_THRESHOLD )); then
         echo "── $repo: $N_FILES files > $LARGE_THRESHOLD, using upload-large-folder"
         echo "   (resumable; commits directly to main — no PR, no custom message)"
         hf upload-large-folder "$repo" . "${EXCLUDES[@]}"
+    elif [[ "$mode" == "direct" ]]; then
+        echo "── uploading (direct → main) to: $repo"
+        hf upload "$repo" . . "${EXCLUDES[@]}" --commit-message="$MSG"
     else
-        echo "── uploading to: $repo"
-        hf upload "$repo" . . \
-            "${EXCLUDES[@]}" \
-            --create-pr \
-            --commit-message="$MSG"
+        echo "── uploading (PR) to: $repo"
+        hf upload "$repo" . . "${EXCLUDES[@]}" --create-pr --commit-message="$MSG"
     fi
 }
 
-upload_repo "$MODEL_REPO"
-upload_repo "$SPACE_REPO"
+# Ensure the personal ZeroGPU Space exists. Tries zero-a10g (needs Pro/ZeroGPU);
+# falls back to cpu-basic so the upload still has a target (set ZeroGPU in
+# Settings afterward). Idempotent via --exist-ok.
+ensure_blade_space() {
+    local id="$BLADE_OWNER/$REPO_NAME"
+    if hf repos create "$id" --type space --space-sdk gradio --flavor zero-a10g --exist-ok 2>/dev/null; then
+        echo "── Space ready (ZeroGPU / zero-a10g): $id"; return 0
+    fi
+    if hf repos create "$id" --type space --space-sdk gradio --exist-ok 2>/dev/null; then
+        echo "── Space created cpu-basic (set ZeroGPU in Settings → Hardware): $id"; return 0
+    fi
+    return 1
+}
+
+blade_help() {
+    cat >&2 <<EOF
+── ⚠ Could not create/deploy to $SPACE_BLADESZASZA_REPO
+   Your active HF token can push to silas-therapy but not create repos under
+   "$BLADE_OWNER". To deploy your own ZeroGPU Space:
+     1) In the HF UI create a Space:  $BLADE_OWNER/$REPO_NAME
+        SDK = Gradio,  Hardware = ZeroGPU (Nvidia A10G).
+     2) Re-auth with a token that can write there:
+          hf auth login        (token with 'Write' role, or fine-grained with
+                                 write access to $BLADE_OWNER)
+     3) Re-run ./scripts/hf_upload.sh
+EOF
+}
 
-echo "✓ done"
+# Shared org repos → PRs; personal ZeroGPU Space → created + direct deploy.
+upload_repo "$MODEL_REPO" pr
+upload_repo "$SPACE_REPO" pr
+
+set +e
+if ensure_blade_space; then
+    upload_repo "$SPACE_BLADESZASZA_REPO" direct || blade_help
+else
+    blade_help
+fi
+set -e
+echo "✓ done (silas-therapy PRs created; see any notes above for the personal Space)"

tests/test_judge_backend.py

@@ -21,9 +21,19 @@ def test_resolve_backend_default_local(monkeypatch):
     assert cfg.resolve_judge_backend() == "llama_cpp"
 
 
-def test_resolve_backend_auto_on_space(monkeypatch):
-    cfg = _reload_config(monkeypatch, FORMSCOUT_JUDGE_BACKEND="auto", SPACE_ID="me/space")
+def test_resolve_backend_auto_on_zero_gpu_space(monkeypatch):
+    cfg = _reload_config(monkeypatch, FORMSCOUT_JUDGE_BACKEND="auto",
+                         SPACE_ID="me/space", SPACES_ZERO_GPU="true")
     assert cfg.resolve_judge_backend() == "transformers"
+    importlib.reload(config)
+
+
+def test_resolve_backend_auto_on_cpu_space_stays_llama(monkeypatch):
+    # A CPU-only Space must NOT load the 17 GB transformers model.
+    cfg = _reload_config(monkeypatch, FORMSCOUT_JUDGE_BACKEND="auto",
+                         SPACE_ID="me/space", SPACES_ZERO_GPU=None, ZERO_GPU=None)
+    assert cfg.resolve_judge_backend() == "llama_cpp"
+    importlib.reload(config)
 
 
 def test_resolve_backend_explicit(monkeypatch):

tests/test_scoresheet.py

@@ -0,0 +1,60 @@
+"""Tests for ScoreSheetAgent — the one-page FMS scoring sheet. No GPU/model downloads."""
+import os
+
+from formscout.types import ReportResult
+
+
+def _report(composite=14, per_test=None, asymmetries=None):
+    return ReportResult(
+        per_test=per_test if per_test is not None else [],
+        composite=composite,
+        asymmetries=asymmetries or [],
+        overlay_video_path=None, pdf_path=None,
+        low_confidence_flags=[], disagreement_flags=[],
+    )
+
+
+def _pt(test_name, score, needs_human=False):
+    return {"test_name": test_name, "score": score, "judge": None,
+            "features": None, "needs_human": needs_human}
+
+
+def test_scoresheet_is_created(tmp_path):
+    from formscout.agents.scoresheet import ScoreSheetAgent
+    report = _report(
+        composite=15,
+        per_test=[
+            _pt("deep_squat", 2),
+            _pt("hurdle_step", 2),
+            _pt("trunk_stability_pushup", 3),
+        ],
+        asymmetries=[{"test": "hurdle_step", "left_score": 2, "right_score": 3, "delta": 1}],
+    )
+    path = ScoreSheetAgent().run(report, str(tmp_path))
+    assert path is not None
+    assert os.path.exists(path)
+    assert os.path.getsize(path) > 1000
+    with open(path, "rb") as f:
+        assert f.read(5) == b"%PDF-"
+
+
+def test_scoresheet_incomplete_composite(tmp_path):
+    """A session with unscored/needs-human tests must still render."""
+    from formscout.agents.scoresheet import ScoreSheetAgent
+    report = _report(
+        composite=None,
+        per_test=[_pt("deep_squat", None, needs_human=True)],
+    )
+    path = ScoreSheetAgent().run(report, str(tmp_path))
+    assert path is not None and os.path.exists(path)
+
+
+def test_scoresheet_accepts_meta(tmp_path):
+    """Optional athlete/meta fields are accepted without breaking rendering."""
+    from formscout.agents.scoresheet import ScoreSheetAgent
+    path = ScoreSheetAgent().run(
+        _report(14, per_test=[_pt("deep_squat", 2)]),
+        str(tmp_path),
+        meta={"name": "Test Athlete", "date": "2026-06-14"},
+    )
+    assert path is not None and os.path.exists(path)