docs: mark full FMS session + PDF export complete in build phases

CLAUDE.md

@@ -172,7 +172,7 @@ The UI uses **Gradio `gr.Blocks`** with custom CSS/theme (`formscout/ui/theme.py
 2. **Phase 1 — Spine:** ✅ Complete. Deep Squat end-to-end.
 3. **Phase 2 — All 7 tests:** ✅ Complete. Classifier, Judge, Report agents; all rubric scorers; Gradio UI.
 4. **Phase 3 — Learned scoring + retrieval:** ST-GCN fine-tune on physio clips, publish to Hub. RetrievalAgent with embedding index.
-5. **Phase 4 — Polish + ship:** Custom Svelte UI components, PDF export, agent trace to Hub, blog post. (Overlay video already done via `PoseVisualizer`.)
+5. **Phase 4 — Polish + ship:** Custom Svelte UI components, agent trace to Hub, blog post. (Overlay video done via `PoseVisualizer`; full 7-test session + PDF export done via `formscout/session.py` + `PdfReportAgent`.)
 
 ## Known issues
 

app.py

@@ -8,6 +8,7 @@ rubric breakdown, and persistent safety banner.
 """
 from __future__ import annotations
 
+import os
 import tempfile
 
 import gradio as gr
@@ -16,6 +17,7 @@ from formscout.pipeline import Director
 from formscout.rubric import score_test
 from formscout.ui.theme import formscout_theme, FORMSCOUT_CSS
 from formscout import config
+from formscout import session as session_mod
 from formscout.startup import ensure_checkpoints
 
 ensure_checkpoints()
@@ -48,22 +50,22 @@ SCORE_DESCRIPTIONS = {
 
 # ─── Processing ──────────────────────────────────────────────────────────────
 
-def process_video(video_path: str, test_name: str, side: str, model_key: str, layers: list[str]):
-    """Process an uploaded video through the FormScout pipeline."""
+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."""
     if not video_path:
         return (
-            _render_empty_state(),
-            "Upload a video to begin analysis.",
-            "",
-            "",
-            None,
-            "",
+            session_state, _render_empty_state(), "Upload a video to begin analysis.",
+            "", "", None, "", _render_session_table(session_state),
+            gr.update(visible=False), gr.update(visible=False),
         )
 
+    if session_state is None:
+        session_state = session_mod.new_session()
+
     director = Director()
     state = director.run(video_path, test_name=test_name, side=side, model_key=model_key)
 
-    # ─── Score card ───
     score_html = _render_empty_state()
     score_details = ""
 
@@ -80,13 +82,21 @@ def process_video(video_path: str, test_name: str, side: str, model_key: str, la
             score_html = _render_score_card(result.score, result.confidence, result.needs_human)
             score_details = _render_score_details(result, state.features)
 
-    # ─── Pipeline info ───
-    pipeline_md = _render_pipeline_status(state)
+        # Accumulate into the session (only when we have a real analysis)
+        if state.ingest and state.pose2d and state.judge:
+            draw_trails = "trails" in {lbl.lower().replace(" ", "_") for lbl in (layers or [])}
+            try:
+                session_mod.add_analysis(
+                    session_state, ingest=state.ingest, pose2d=state.pose2d,
+                    features=state.features, judge=state.judge,
+                    test_name=test_name, side=side, draw_trails=draw_trails,
+                )
+            except Exception as e:
+                state.warnings.append(f"session accumulation failed: {e}")
 
-    # ─── Warnings/errors ───
+    pipeline_md = _render_pipeline_status(state)
     alerts = _render_alerts(state)
 
-    # ─── Overlay video ───
     overlay_path = None
     vel_summary = ""
     layer_set = {lbl.lower().replace(" ", "_") for lbl in (layers or [])}
@@ -102,7 +112,12 @@ def process_video(video_path: str, test_name: str, side: str, model_key: str, la
         except Exception as e:
             alerts = (alerts or "") + f"\n⚠️ Visualizer error: {e}"
 
-    return score_html, pipeline_md, score_details, alerts, overlay_path, vel_summary
+    has_entries = bool(session_state and session_state.entries)
+    return (
+        session_state, score_html, pipeline_md, score_details, alerts,
+        overlay_path, vel_summary, _render_session_table(session_state),
+        gr.update(visible=has_entries), gr.update(visible=has_entries),
+    )
 
 
 def _render_score_card(score: int, confidence: float, needs_human: bool) -> str:
@@ -242,12 +257,64 @@ def _render_alerts(state) -> str:
     return "\n\n".join(parts)
 
 
+def _render_session_table(session_state) -> str:
+    """Render the accumulated 'Session so far' table as markdown."""
+    if not session_state or not session_state.entries:
+        return "*No clips analysed yet.*"
+    lines = ["| Test | Side | Score | Status |", "|---|---|---|---|"]
+    for e in session_state.entries:
+        test = e.test_name.replace("_", " ").title()
+        side = e.side if e.side in ("left", "right") else "—"
+        if e.needs_human:
+            score, status = "—", "⚠️ Clinician review"
+        else:
+            score, status = f"{e.score}/3", "✓ scored"
+        lines.append(f"| {test} | {side} | {score} | {status} |")
+    return "\n".join(lines)
+
+
+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)
+
+    report, pdf_path = session_mod.finish_session(session_state)
+    if report is None:
+        return ("⚠️ Nothing to report.", None, None)
+
+    if report.composite is not None:
+        summary = [f"## Composite: {report.composite} / 21"]
+    else:
+        n = len(session_state.entries)
+        summary = [f"## Composite: Incomplete — {n}/7 tests scored",
+                   "*(One or more tests need clinician review or were unscored.)*"]
+
+    if report.asymmetries:
+        summary.append("\n### Asymmetries")
+        for a in report.asymmetries:
+            test = a["test"].replace("_", " ").title()
+            summary.append(f"- **{test}:** L={a['left_score']} R={a['right_score']} (Δ {a['delta']})")
+
+    flags = list(report.low_confidence_flags) + list(report.disagreement_flags)
+    if flags:
+        summary.append("\n### Flags")
+        for fl in flags:
+            summary.append(f"- {fl}")
+
+    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
+
+
 # ─── App Builder ─────────────────────────────────────────────────────────────
 
 def build_app() -> gr.Blocks:
     """Build the FormScout Gradio app with custom scout/trail theme."""
     with gr.Blocks(title="FormScout — FMS Screening Aid") as app:
 
+        session_state = gr.State(None)
+
         # Header
         gr.HTML("""
         <div class="formscout-header">
@@ -304,6 +371,10 @@ def build_app() -> gr.Blocks:
                     variant="primary",
                     size="lg",
                 )
+                with gr.Row():
+                    new_clip_btn = gr.Button("➕ Analyse new clip", visible=False)
+                    finish_btn = gr.Button("✅ Finish & generate PDF",
+                                           variant="primary", visible=False)
 
                 gr.Markdown(
                     "*Tip: Film from the side at hip height for best accuracy. "
@@ -333,6 +404,12 @@ def build_app() -> gr.Blocks:
                         overlay_video = gr.Video(label="Annotated Movement")
                         velocity_md = gr.Markdown("")
 
+                    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)
+                        md_file = gr.File(label="Analysis Log (Markdown)", visible=True)
+
         # Footer safety banner
         gr.HTML(f'<div class="safety-banner" style="margin-top: 20px;">{DISCLAIMER}</div>')
 
@@ -345,17 +422,35 @@ def build_app() -> gr.Blocks:
 
         # ─── Event wiring ────────────────────────────────────────────────────
 
-        def _map_inputs(video, test_display_name, side_display, pose_model_key, overlay_layers):
-            """Map UI display values to internal values."""
+        def _map_inputs(video, test_display_name, side_display, pose_model_key, overlay_layers, sess):
+            """Map UI display values to internal values and accumulate into the session."""
             test_map = {name: val for name, val in FMS_TESTS}
             test_name = test_map.get(test_display_name, "deep_squat")
             side = {"N/A": "na", "Left": "left", "Right": "right"}.get(side_display, "na")
-            return process_video(video, test_name, side, pose_model_key, overlay_layers)
+            return process_video(video, test_name, side, pose_model_key, overlay_layers, sess)
 
         submit_btn.click(
             fn=_map_inputs,
-            inputs=[video_input, test_dropdown, side_dropdown, pose_model_dropdown, overlay_layers],
-            outputs=[score_html, pipeline_md, score_details, alerts_md, overlay_video, velocity_md],
+            inputs=[video_input, test_dropdown, side_dropdown, pose_model_dropdown,
+                    overlay_layers, session_state],
+            outputs=[session_state, score_html, pipeline_md, score_details, alerts_md,
+                     overlay_video, velocity_md, session_table, new_clip_btn, finish_btn],
+        )
+
+        def _new_clip():
+            """Clear inputs for the next clip; keep the session intact."""
+            return None, _render_empty_state(), ""
+
+        new_clip_btn.click(
+            fn=_new_clip,
+            inputs=[],
+            outputs=[video_input, score_html, score_details],
+        )
+
+        finish_btn.click(
+            fn=_finish_session,
+            inputs=[session_state],
+            outputs=[finish_summary, pdf_file, md_file],
         )
 
     return app

docs/superpowers/plans/2026-06-13-full-fms-session-pdf.md

@@ -0,0 +1,1209 @@
+# Full FMS Session + PDF Report — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Turn FormScout's one-clip scorer into a screening session that accumulates analyzed clips into a composite 0–21 report and exports a branded PDF with annotated worst-moment key-frame stills.
+
+**Architecture:** A new `formscout/session.py` accumulates typed `SessionEntry` objects (one per analyzed clip), persisting each to a temp session dir. `PoseVisualizer.render_frame()` captures the governing frame (already computed by `BiomechanicsAgent` and stored in `features.timing`) as an annotated PNG. On "Finish", the existing `ReportAgent` computes composite + asymmetries, and a new `PdfReportAgent` renders a ReportLab PDF. The UI (`app.py`) gains `gr.State` session accumulation with "Analyse new clip" / "Finish & generate PDF" buttons.
+
+**Tech Stack:** Python 3.13, ReportLab (new dep), OpenCV (existing), Gradio 5, pytest. No model downloads in tests.
+
+---
+
+## File Structure
+
+- `requirements.txt` — add `reportlab`.
+- `formscout/types.py` — add `SessionEntry` frozen dataclass.
+- `formscout/agents/biomechanics.py` — add `max_sag_frame` to `trunk_stability_pushup` timing (rotary already has `peak_extension_frame`).
+- `formscout/agents/visualizer.py` — add `PoseVisualizer.render_frame()`.
+- `formscout/session.py` — **new**: session accumulator (new/add/finish + persistence + key-frame helpers).
+- `formscout/agents/pdf_report.py` — **new**: `PdfReportAgent` (ReportLab).
+- `app.py` — wire `gr.State`, two buttons, "Session so far" table, finish handler.
+- `tests/test_session.py`, `tests/test_keyframe.py`, `tests/test_pdf_report.py` — **new**.
+
+---
+
+## Task 1: Add ReportLab dependency
+
+**Files:**
+- Modify: `requirements.txt`
+
+- [ ] **Step 1: Add the dependency**
+
+Add this line to `requirements.txt` (after `pillow>=10.3`):
+
+```
+reportlab>=4.0
+```
+
+- [ ] **Step 2: Install it**
+
+Run: `pip install 'reportlab>=4.0'`
+Expected: `Successfully installed reportlab-4.x.x`
+
+- [ ] **Step 3: Verify import**
+
+Run: `python3 -c "import reportlab; print(reportlab.Version)"`
+Expected: prints a version like `4.x.x`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add requirements.txt
+git commit -m "build: add reportlab for PDF report generation"
+```
+
+---
+
+## Task 2: Add `SessionEntry` dataclass
+
+**Files:**
+- Modify: `formscout/types.py` (after `ReportResult`, before `PipelineState`)
+- Test: `tests/test_session.py`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_session.py` with:
+
+```python
+"""Tests for the FMS session accumulator — no GPU, no model downloads."""
+import numpy as np
+
+from formscout.types import (
+    IngestResult, Pose2DResult, BiomechFeatures, ScoreResult, JudgeResult,
+    MovementResult, SessionEntry,
+)
+
+
+def test_session_entry_holds_typed_objects():
+    movement = MovementResult(test_name="deep_squat", side="na", confidence=1.0)
+    features = BiomechFeatures(
+        test_name="deep_squat", view="2d", side="na",
+        angles={"left_knee_flexion_deg": 95.0}, alignments={"knees_tracking_over_feet": True},
+        symmetry_delta=None, timing={"deepest_frame": 2}, confidence=0.9,
+    )
+    rubric = ScoreResult(score=2, rationale="ok", confidence=0.8)
+    judge = JudgeResult(score=2, rationale="ok", compensation_tags=["heels elevated"],
+                        corrective_hint="ankle mobility", confidence=0.85)
+    entry = SessionEntry(
+        test_name="deep_squat", side="na", score=2, needs_human=False,
+        rationale="ok", compensation_tags=["heels elevated"], corrective_hint="ankle mobility",
+        measurements={"left_knee_flexion_deg": 95.0}, confidence=0.85, view="2d",
+        keyframe_path=None, movement=movement, features=features,
+        rubric_score=rubric, judge=judge,
+    )
+    assert entry.score == 2
+    assert entry.movement.test_name == "deep_squat"
+    assert entry.rubric_score.score == 2
+    assert entry.judge.compensation_tags == ["heels elevated"]
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_session.py::test_session_entry_holds_typed_objects -v`
+Expected: FAIL with `ImportError: cannot import name 'SessionEntry'`
+
+- [ ] **Step 3: Add the dataclass**
+
+In `formscout/types.py`, insert after the `ReportResult` class (line ~142) and before `PipelineState`:
+
+```python
+@dataclass(frozen=True)
+class SessionEntry:
+    """One accumulated analysis in a screening session.
+
+    Display fields (test_name…keyframe_path) feed the PDF/JSON/MD artifacts;
+    the trailing typed objects (movement…judge) feed ReportAgent.run().
+    """
+    test_name: str
+    side: str
+    score: int | None
+    needs_human: bool
+    rationale: str
+    compensation_tags: list
+    corrective_hint: str
+    measurements: dict
+    confidence: float
+    view: str
+    keyframe_path: str | None
+    movement: MovementResult
+    features: BiomechFeatures
+    rubric_score: ScoreResult
+    judge: JudgeResult | None
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pytest tests/test_session.py::test_session_entry_holds_typed_objects -v`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add formscout/types.py tests/test_session.py
+git commit -m "feat: add SessionEntry typed contract for screening sessions"
+```
+
+---
+
+## Task 3: Add governing-frame index to push-up biomechanics
+
+**Files:**
+- Modify: `formscout/agents/biomechanics.py:468-529` (`_trunk_stability_pushup`)
+- Test: `tests/test_biomechanics.py` (append a test)
+
+The other six tests already store a governing frame index in `features.timing`
+(`deepest_frame`, `peak_step_frame`, `deepest_lunge_frame`, `measure_frame`,
+`peak_raise_frame`, `peak_extension_frame`). Only `trunk_stability_pushup` is missing one.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/test_biomechanics.py`:
+
+```python
+def test_pushup_timing_has_max_sag_frame():
+    from formscout.agents.biomechanics import BiomechanicsAgent
+    from formscout.types import Pose2DResult, Body3DResult, MovementResult
+
+    # 4 frames; frame 2 has the largest hip sag (hip far below shoulder/ankle midline)
+    def kps(hip_y):
+        base = {
+            5: {"x": 200, "y": 200, "conf": 0.9},   # L shoulder
+            6: {"x": 220, "y": 200, "conf": 0.9},   # R shoulder
+            11: {"x": 300, "y": hip_y, "conf": 0.9}, # L hip
+            12: {"x": 320, "y": hip_y, "conf": 0.9}, # R hip
+            15: {"x": 400, "y": 200, "conf": 0.9},   # L ankle
+            16: {"x": 420, "y": 200, "conf": 0.9},   # R ankle
+        }
+        return base
+
+    frames = [kps(200), kps(210), kps(260), kps(205)]
+    pose = Pose2DResult(keypoints=frames, fps=30.0, confidence=0.9)
+    body3d = Body3DResult(used=False, joints_3d=[])
+    movement = MovementResult(test_name="trunk_stability_pushup", side="na", confidence=1.0)
+
+    feats = BiomechanicsAgent().run(pose, body3d, movement)
+    assert "max_sag_frame" in feats.timing
+    assert feats.timing["max_sag_frame"] == 2
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_biomechanics.py::test_pushup_timing_has_max_sag_frame -v`
+Expected: FAIL with `assert 'max_sag_frame' in {...}` (KeyError-style assertion failure)
+
+- [ ] **Step 3: Track the max-sag frame index**
+
+In `formscout/agents/biomechanics.py`, replace the body of `_trunk_stability_pushup` from the
+`trunk_angles_over_time = []` loop through the `if trunk_angles_over_time:` block. Replace:
+
+```python
+        # Analyze multiple frames to detect sag/lag
+        trunk_angles_over_time = []
+        for i, kps in enumerate(pose2d.keypoints):
+```
+
+…down to and including the `alignments["no_sag"] = max_sag < 30` line, with:
+
+```python
+        # Analyze multiple frames to detect sag/lag
+        trunk_sags: list[tuple[int, float]] = []  # (frame_idx, sag_px)
+        for i, kps in enumerate(pose2d.keypoints):
+            l_sh = _get_joint(kps, L_SHOULDER)
+            r_sh = _get_joint(kps, R_SHOULDER)
+            l_hip = _get_joint(kps, L_HIP)
+            r_hip = _get_joint(kps, R_HIP)
+            l_ankle = _get_joint(kps, L_ANKLE)
+            r_ankle = _get_joint(kps, R_ANKLE)
+
+            if l_sh and r_sh and l_hip and r_hip and l_ankle and r_ankle:
+                sh_y = (l_sh[1] + r_sh[1]) / 2
+                hip_y = (l_hip[1] + r_hip[1]) / 2
+                ankle_y = (l_ankle[1] + r_ankle[1]) / 2
+                expected_hip_y = (sh_y + ankle_y) / 2
+                sag_px = hip_y - expected_hip_y
+                trunk_sags.append((i, sag_px))
+
+        max_sag_frame = 0
+        if trunk_sags:
+            sags = [s for _, s in trunk_sags]
+            max_sag_frame = max(trunk_sags, key=lambda t: t[1])[0]
+            mean = sum(sags) / len(sags)
+            variance = (sum((x - mean) ** 2 for x in sags) / len(sags)) ** 0.5
+            max_sag = max(sags)
+            angles["max_sag_px"] = max_sag
+            angles["trunk_variance_px"] = variance
+            alignments["body_rigid"] = max_sag < 30 and variance < 15
+            alignments["no_sag"] = max_sag < 30
+        else:
+            notes_parts.append("insufficient landmarks for trunk analysis")
+```
+
+Then update the `return BiomechFeatures(...)` `timing=` argument at the end of the method from:
+
+```python
+            timing={"n_frames_analyzed": len(trunk_angles_over_time)},
+```
+
+to:
+
+```python
+            timing={"n_frames_analyzed": len(trunk_sags), "max_sag_frame": max_sag_frame},
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pytest tests/test_biomechanics.py::test_pushup_timing_has_max_sag_frame -v`
+Expected: PASS
+
+- [ ] **Step 5: Run the full biomechanics suite (no regressions)**
+
+Run: `pytest tests/test_biomechanics.py -v`
+Expected: all previously-passing tests still pass (the pre-existing `test_unimplemented_test_returns_low_confidence` known-failure may remain failing — that is unrelated and documented in CLAUDE.md).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add formscout/agents/biomechanics.py tests/test_biomechanics.py
+git commit -m "feat: track max-sag frame index in push-up biomechanics for key-frame capture"
+```
+
+---
+
+## Task 4: Add `PoseVisualizer.render_frame()`
+
+**Files:**
+- Modify: `formscout/agents/visualizer.py` (add method to `PoseVisualizer`, after `render_video`)
+- Test: `tests/test_keyframe.py`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_keyframe.py`:
+
+```python
+"""Tests for PoseVisualizer.render_frame — single annotated still."""
+import os
+import numpy as np
+
+from formscout.types import IngestResult, Pose2DResult
+
+
+def _ingest(n=5, h=480, w=640):
+    frames = [np.zeros((h, w, 3), dtype=np.uint8) for _ in range(n)]
+    return IngestResult(frames=frames, fps=30.0, duration=n / 30.0, n_people=1, width=w, height=h)
+
+
+def _pose(n=5):
+    kps = []
+    for i in range(n):
+        kps.append({j: {"x": float(50 + j * 25), "y": float(80 + j * 18), "conf": 0.9}
+                    for j in range(17)})
+    return Pose2DResult(keypoints=kps, fps=30.0, confidence=0.9)
+
+
+def test_render_frame_writes_png(tmp_path):
+    from formscout.agents.visualizer import PoseVisualizer
+    out = str(tmp_path / "key.png")
+    path = PoseVisualizer().render_frame(_ingest(), _pose(), frame_idx=2,
+                                         layers={"skeleton"}, caption="Deep Squat — heels elevated",
+                                         out_png=out)
+    assert path == out
+    assert os.path.exists(out)
+    assert os.path.getsize(out) > 0
+
+
+def test_render_frame_bad_index_returns_none(tmp_path):
+    from formscout.agents.visualizer import PoseVisualizer
+    out = str(tmp_path / "key.png")
+    path = PoseVisualizer().render_frame(_ingest(n=3), _pose(n=3), frame_idx=99,
+                                         layers={"skeleton"}, caption="", out_png=out)
+    assert path is None
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_keyframe.py -v`
+Expected: FAIL with `AttributeError: 'PoseVisualizer' object has no attribute 'render_frame'`
+
+- [ ] **Step 3: Add the method**
+
+In `formscout/agents/visualizer.py`, inside the `PoseVisualizer` class, add this method
+immediately after `render_video` (before the closing of the class / the module-level
+`build_velocity_summary`):
+
+```python
+    def render_frame(
+        self,
+        ingest,
+        pose2d,
+        frame_idx: int,
+        layers: set[str],
+        caption: str = "",
+        out_png: str | None = None,
+    ) -> str | None:
+        """Render a single annotated still (skeleton + optional trails + caption).
+
+        frame_idx is typically the governing frame from BiomechFeatures.timing.
+        Returns the PNG path on success, None on any failure. Never raises.
+        """
+        try:
+            if not (0 <= frame_idx < len(ingest.frames)) or frame_idx >= len(pose2d.keypoints):
+                return None
+
+            frame = ingest.frames[frame_idx].copy()
+            kps = pose2d.keypoints[frame_idx]
+
+            if "trails" in layers:
+                trail: dict[int, deque] = {j: deque(maxlen=TRAIL_LENGTH) for j in range(17)}
+                start = max(0, frame_idx - TRAIL_LENGTH)
+                for fi in range(start, frame_idx + 1):
+                    for j, kp in pose2d.keypoints[fi].items():
+                        if kp.get("conf", 0.0) >= CONF_THRESHOLD:
+                            trail[j].append((kp["x"], kp["y"]))
+                frame = self._draw_trails(frame, trail)
+
+            if "skeleton" in layers:
+                frame = self._draw_skeleton(frame, kps)
+
+            if caption:
+                cv2.rectangle(frame, (0, 0), (frame.shape[1], 28), (0, 0, 0), -1)
+                cv2.putText(frame, caption[:80], (8, 20), cv2.FONT_HERSHEY_SIMPLEX,
+                            0.55, (255, 255, 255), 1, cv2.LINE_AA)
+
+            if out_png is None:
+                out_png = tempfile.NamedTemporaryFile(suffix=".png", delete=False).name
+
+            ok = cv2.imwrite(out_png, frame)
+            return out_png if ok else None
+        except Exception as e:
+            logger.warning("render_frame failed: %s", e)
+            return None
+```
+
+(`deque`, `cv2`, `tempfile`, `logger`, `TRAIL_LENGTH`, `CONF_THRESHOLD` are all already imported at the top of this file.)
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pytest tests/test_keyframe.py -v`
+Expected: both tests PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add formscout/agents/visualizer.py tests/test_keyframe.py
+git commit -m "feat: add PoseVisualizer.render_frame for annotated key-frame stills"
+```
+
+---
+
+## Task 5: Create the session accumulator
+
+**Files:**
+- Create: `formscout/session.py`
+- Test: `tests/test_session.py` (append tests)
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/test_session.py`:
+
+```python
+def _ingest(n=5, h=480, w=640):
+    frames = [np.zeros((h, w, 3), dtype=np.uint8) for _ in range(n)]
+    return IngestResult(frames=frames, fps=30.0, duration=n / 30.0, n_people=1, width=w, height=h)
+
+
+def _pose(n=5):
+    kps = []
+    for i in range(n):
+        kps.append({j: {"x": float(50 + j * 25), "y": float(80 + j * 18), "conf": 0.9}
+                    for j in range(17)})
+    return Pose2DResult(keypoints=kps, fps=30.0, confidence=0.9)
+
+
+def _features(test_name="deep_squat", side="na", frame_key="deepest_frame"):
+    return BiomechFeatures(
+        test_name=test_name, view="2d", side=side,
+        angles={"left_knee_flexion_deg": 95.0},
+        alignments={"knees_tracking_over_feet": False},
+        symmetry_delta=None, timing={frame_key: 2}, confidence=0.9,
+    )
+
+
+def _judge(score=2, needs_human=False):
+    return JudgeResult(
+        score=None if needs_human else score, rationale="r",
+        compensation_tags=["heels elevated"], corrective_hint="ankle mobility",
+        confidence=0.85, needs_human=needs_human,
+    )
+
+
+def test_add_analysis_appends_entry_and_writes_files():
+    import os
+    from formscout import session as S
+    sess = S.new_session()
+    entry = S.add_analysis(sess, ingest=_ingest(), pose2d=_pose(),
+                           features=_features(), judge=_judge(), test_name="deep_squat", side="na")
+    assert len(sess.entries) == 1
+    assert entry.score == 2
+    assert os.path.exists(os.path.join(sess.session_dir, "session.json"))
+    assert os.path.exists(os.path.join(sess.session_dir, "analysis.md"))
+    # key-frame still written (deepest_frame=2 is valid)
+    assert entry.keyframe_path and os.path.exists(entry.keyframe_path)
+
+
+def test_finish_composite_null_when_needs_human():
+    from formscout import session as S
+    sess = S.new_session()
+    S.add_analysis(sess, ingest=_ingest(), pose2d=_pose(), features=_features(),
+                   judge=_judge(score=3), test_name="deep_squat", side="na")
+    S.add_analysis(sess, ingest=_ingest(), pose2d=_pose(),
+                   features=_features("trunk_stability_pushup", frame_key="max_sag_frame"),
+                   judge=_judge(needs_human=True), test_name="trunk_stability_pushup", side="na")
+    report, pdf_path = S.finish_session(sess)
+    assert report is not None
+    assert report.composite is None  # one test needs_human
+
+
+def test_finish_empty_session_returns_none():
+    from formscout import session as S
+    sess = S.new_session()
+    report, pdf_path = S.finish_session(sess)
+    assert report is None and pdf_path is None
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `pytest tests/test_session.py -v`
+Expected: the three new tests FAIL with `ModuleNotFoundError: No module named 'formscout.session'`
+
+- [ ] **Step 3: Create the module**
+
+Create `formscout/session.py`:
+
+```python
+"""
+Screening-session accumulator.
+
+Accumulates one SessionEntry per analyzed clip, persists each to a temp session
+dir (session.json + analysis.md + key-frame PNGs), and on finish builds a
+ReportResult (via ReportAgent) + a PDF (via PdfReportAgent).
+
+Pure orchestration — no Gradio imports. Disk writes tolerate failure with a
+logged warning and never block scoring.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+import uuid
+from dataclasses import dataclass, replace
+
+from formscout.rubric import score_test
+from formscout.types import MovementResult, ReportResult, SessionEntry
+
+logger = logging.getLogger(__name__)
+
+# Maps each test to the BiomechFeatures.timing key holding its governing frame.
+TIMING_KEY = {
+    "deep_squat": "deepest_frame",
+    "hurdle_step": "peak_step_frame",
+    "inline_lunge": "deepest_lunge_frame",
+    "shoulder_mobility": "measure_frame",
+    "active_slr": "peak_raise_frame",
+    "trunk_stability_pushup": "max_sag_frame",
+    "rotary_stability": "peak_extension_frame",
+}
+
+
+@dataclass
+class Session:
+    """Mutable session: an id, its temp dir, and accumulated entries."""
+    session_id: str
+    session_dir: str
+    entries: list  # list[SessionEntry]
+
+
+def new_session() -> Session:
+    sid = uuid.uuid4().hex[:12]
+    base = os.path.join(tempfile.gettempdir(), "formscout_sessions", sid)
+    try:
+        os.makedirs(os.path.join(base, "keyframes"), exist_ok=True)
+    except Exception as e:
+        logger.warning("session dir create failed: %s", e)
+    return Session(session_id=sid, session_dir=base, entries=[])
+
+
+def governing_frame_index(features) -> int | None:
+    """Return the governing frame index for this test, or None."""
+    key = TIMING_KEY.get(features.test_name)
+    if key is None:
+        return None
+    idx = features.timing.get(key)
+    return int(idx) if isinstance(idx, (int, float)) else None
+
+
+def worst_compensation_caption(judge, features) -> str:
+    """Short caption naming the worst compensation for the key-frame still."""
+    if judge and getattr(judge, "compensation_tags", None):
+        return ", ".join(judge.compensation_tags)
+    failed = [k.replace("_", " ") for k, v in features.alignments.items() if v is False]
+    return ("compensation: " + ", ".join(failed)) if failed else "key position"
+
+
+def add_analysis(session, *, ingest, pose2d, features, judge, test_name, side,
+                 draw_trails: bool = False) -> SessionEntry:
+    """Build a SessionEntry from a completed analysis, render its key-frame,
+    persist the session, append, and return the entry."""
+    movement = MovementResult(test_name=test_name, side=side, confidence=1.0)
+    rubric = score_test(features)
+
+    needs_human = bool((judge and judge.needs_human) or rubric.needs_human)
+    if needs_human:
+        score = None
+    elif judge and judge.score is not None:
+        score = judge.score
+    else:
+        score = rubric.score
+
+    keyframe_path = None
+    idx = governing_frame_index(features)
+    if idx is not None and 0 <= idx < len(pose2d.keypoints):
+        from formscout.agents.visualizer import PoseVisualizer
+        caption = (f"{test_name.replace('_', ' ').title()} "
+                   f"({side}) — {worst_compensation_caption(judge, features)}")
+        layers = {"skeleton", "trails"} if draw_trails else {"skeleton"}
+        out_png = os.path.join(session.session_dir, "keyframes", f"{test_name}_{side}.png")
+        try:
+            keyframe_path = PoseVisualizer().render_frame(ingest, pose2d, idx, layers, caption, out_png)
+        except Exception as e:
+            logger.warning("keyframe render failed: %s", e)
+
+    measurements = {}
+    measurements.update(features.angles)
+    measurements.update(features.alignments)
+
+    entry = SessionEntry(
+        test_name=test_name, side=side, score=score, needs_human=needs_human,
+        rationale=(judge.rationale if judge else rubric.rationale),
+        compensation_tags=list(judge.compensation_tags) if judge else [],
+        corrective_hint=(judge.corrective_hint if judge else ""),
+        measurements=measurements,
+        confidence=(judge.confidence if judge else rubric.confidence),
+        view=features.view,
+        keyframe_path=keyframe_path,
+        movement=movement, features=features, rubric_score=rubric, judge=judge,
+    )
+    session.entries.append(entry)
+    _persist(session)
+    return entry
+
+
+def finish_session(session) -> tuple[ReportResult | None, str | None]:
+    """Build the composite report + PDF. Returns (report, pdf_path).
+    Returns (None, None) for an empty session."""
+    if not session.entries:
+        return None, None
+
+    from formscout.agents.report import ReportAgent
+    report_inputs = [{
+        "movement": e.movement, "features": e.features,
+        "rubric_score": e.rubric_score, "judge": e.judge, "side": e.side,
+    } for e in session.entries]
+    report = ReportAgent().run(report_inputs)
+
+    pdf_path = None
+    try:
+        from formscout.agents.pdf_report import PdfReportAgent
+        pdf_path = PdfReportAgent().run(report, session.entries, session.session_dir)
+    except Exception as e:
+        logger.warning("pdf generation failed: %s", e)
+
+    report = replace(report, pdf_path=pdf_path)
+    return report, pdf_path
+
+
+# ── Persistence ───────────────────────────────────────────────────────────────
+
+def _jsonable(d: dict) -> dict:
+    out = {}
+    for k, v in d.items():
+        if isinstance(v, float):
+            out[k] = round(v, 2)
+        elif isinstance(v, (int, str, bool)) or v is None:
+            out[k] = v
+        else:
+            out[k] = str(v)
+    return out
+
+
+def _entry_display(e: SessionEntry) -> dict:
+    return {
+        "test_name": e.test_name, "side": e.side, "score": e.score,
+        "needs_human": e.needs_human, "rationale": e.rationale,
+        "compensation_tags": list(e.compensation_tags), "corrective_hint": e.corrective_hint,
+        "measurements": _jsonable(e.measurements), "confidence": round(e.confidence, 2),
+        "view": e.view, "keyframe_path": e.keyframe_path,
+    }
+
+
+def _render_markdown(session: Session) -> str:
+    lines = ["# FormScout — Session Log", ""]
+    for e in session.entries:
+        title = e.test_name.replace("_", " ").title()
+        if e.side in ("left", "right"):
+            title += f" ({e.side})"
+        score = "Clinician review required" if e.needs_human else f"{e.score}/3"
+        lines.append(f"## {title} — {score}")
+        lines.append(e.rationale or "")
+        if e.compensation_tags:
+            lines.append(f"- Compensations: {', '.join(e.compensation_tags)}")
+        if e.corrective_hint:
+            lines.append(f"- Corrective: {e.corrective_hint}")
+        if e.keyframe_path:
+            lines.append(f"- Key frame: `{e.keyframe_path}`")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _persist(session: Session) -> None:
+    try:
+        with open(os.path.join(session.session_dir, "session.json"), "w") as f:
+            json.dump([_entry_display(e) for e in session.entries], f, indent=2)
+        with open(os.path.join(session.session_dir, "analysis.md"), "w") as f:
+            f.write(_render_markdown(session))
+    except Exception as e:
+        logger.warning("session persist failed: %s", e)
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `pytest tests/test_session.py -v`
+Expected: all session tests PASS (Task 6 provides `PdfReportAgent`; `finish_session` tolerates its
+absence via the try/except, so these pass now — `pdf_path` may be `None` until Task 6).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add formscout/session.py tests/test_session.py
+git commit -m "feat: add screening-session accumulator with key-frame capture and persistence"
+```
+
+---
+
+## Task 6: Create `PdfReportAgent`
+
+**Files:**
+- Create: `formscout/agents/pdf_report.py`
+- Test: `tests/test_pdf_report.py`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_pdf_report.py`:
+
+```python
+"""Tests for PdfReportAgent — no GPU, no model downloads."""
+import os
+
+from formscout.types import (
+    ReportResult, SessionEntry, MovementResult, BiomechFeatures, ScoreResult, JudgeResult,
+)
+
+
+def _entry(test_name="deep_squat", score=2, needs_human=False):
+    movement = MovementResult(test_name=test_name, side="na", confidence=1.0)
+    features = BiomechFeatures(
+        test_name=test_name, view="2d", side="na",
+        angles={"left_knee_flexion_deg": 95.0}, alignments={"knees_tracking_over_feet": False},
+        symmetry_delta=None, timing={"deepest_frame": 1}, confidence=0.9,
+    )
+    rubric = ScoreResult(score=2, rationale="rubric ok", confidence=0.8)
+    judge = JudgeResult(score=None if needs_human else score, rationale="judge rationale",
+                        compensation_tags=["heels elevated"], corrective_hint="ankle mobility",
+                        confidence=0.85, needs_human=needs_human)
+    return SessionEntry(
+        test_name=test_name, side="na", score=None if needs_human else score,
+        needs_human=needs_human, rationale="judge rationale",
+        compensation_tags=["heels elevated"], corrective_hint="ankle mobility",
+        measurements={"left_knee_flexion_deg": 95.0, "knees_tracking_over_feet": False},
+        confidence=0.85, view="2d", keyframe_path=None,
+        movement=movement, features=features, rubric_score=rubric, judge=judge,
+    )
+
+
+def _report(composite=2):
+    return ReportResult(
+        per_test=[], composite=composite, asymmetries=[],
+        overlay_video_path=None, pdf_path=None,
+        low_confidence_flags=[], disagreement_flags=[],
+    )
+
+
+def test_pdf_is_created(tmp_path):
+    from formscout.agents.pdf_report import PdfReportAgent
+    path = PdfReportAgent().run(_report(2), [_entry()], str(tmp_path))
+    assert path is not None
+    assert os.path.exists(path)
+    assert os.path.getsize(path) > 1000  # a real PDF, not an empty file
+    with open(path, "rb") as f:
+        assert f.read(5) == b"%PDF-"
+
+
+def test_pdf_handles_incomplete_composite(tmp_path):
+    from formscout.agents.pdf_report import PdfReportAgent
+    path = PdfReportAgent().run(_report(None), [_entry(needs_human=True)], str(tmp_path))
+    assert path is not None and os.path.exists(path)
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_pdf_report.py -v`
+Expected: FAIL with `ModuleNotFoundError: No module named 'formscout.agents.pdf_report'`
+
+- [ ] **Step 3: Create the agent**
+
+Create `formscout/agents/pdf_report.py`:
+
+```python
+"""
+PdfReportAgent — renders a ReportResult + session entries to a branded PDF.
+
+Input:  ReportResult, list[SessionEntry], session_dir (str)
+Output: path to the written PDF (str), or None on failure.
+Failure: returns None, never raises.
+Params: 0 (pure rendering — no model).
+License: n/a.
+Gated: no.
+"""
+from __future__ import annotations
+
+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."
+
+
+class PdfReportAgent:
+    """Assembles the screening-session PDF via ReportLab."""
+
+    def run(self, report: ReportResult, entries: list, session_dir: str) -> 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 (
+                Image, 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_report.pdf")
+        try:
+            styles = getSampleStyleSheet()
+            banner = ParagraphStyle(
+                "banner", parent=styles["Normal"], fontSize=9, textColor=colors.white,
+                backColor=colors.HexColor("#b45309"), alignment=1, borderPadding=6, spaceAfter=12,
+            )
+            story = []
+            story.append(Paragraph(f"<b>&#9888; {DISCLAIMER}</b>", banner))
+            story.append(Paragraph("FormScout — FMS Screening Report", styles["Title"]))
+
+            if report.composite is not None:
+                comp = f"Composite: <b>{report.composite} / 21</b>"
+            else:
+                comp = f"Composite: <b>Incomplete</b> — {len(entries)}/7 tests scored"
+            story.append(Paragraph(comp, styles["Heading2"]))
+            story.append(Spacer(1, 0.2 * inch))
+
+            for e in entries:
+                title = e.test_name.replace("_", " ").title()
+                if e.side in ("left", "right"):
+                    title += f" ({e.side})"
+                score_txt = "Clinician review required" if e.needs_human else f"Score: {e.score}/3"
+                story.append(Paragraph(f"<b>{title}</b> — {score_txt}", styles["Heading3"]))
+                if e.rationale:
+                    story.append(Paragraph(e.rationale, styles["Normal"]))
+                if e.compensation_tags:
+                    story.append(Paragraph("Compensations: " + ", ".join(e.compensation_tags),
+                                           styles["Normal"]))
+                if e.corrective_hint:
+                    story.append(Paragraph("Corrective: " + e.corrective_hint, styles["Normal"]))
+
+                items = list(e.measurements.items())[:6]
+                if items:
+                    rows = [[k.replace("_", " "),
+                             (f"{v:.1f}" if isinstance(v, float) else str(v))] for k, v in items]
+                    tbl = Table(rows, colWidths=[3 * inch, 1.5 * inch])
+                    tbl.setStyle(TableStyle([
+                        ("FONTSIZE", (0, 0), (-1, -1), 8),
+                        ("TEXTCOLOR", (0, 0), (-1, -1), colors.HexColor("#334155")),
+                    ]))
+                    story.append(tbl)
+
+                if e.keyframe_path and os.path.exists(e.keyframe_path):
+                    try:
+                        story.append(Image(e.keyframe_path, width=3.0 * inch, height=2.25 * inch))
+                    except Exception:
+                        story.append(Paragraph("<i>(key-frame image unavailable)</i>", styles["Normal"]))
+                else:
+                    story.append(Paragraph("<i>(key-frame image unavailable)</i>", styles["Normal"]))
+
+                story.append(Spacer(1, 0.2 * inch))
+
+            if report.asymmetries:
+                story.append(Paragraph("Asymmetries", styles["Heading2"]))
+                for a in report.asymmetries:
+                    story.append(Paragraph(
+                        f"{a['test'].replace('_', ' ').title()}: "
+                        f"L={a['left_score']} R={a['right_score']} (&#916; {a['delta']})",
+                        styles["Normal"]))
+
+            flags = list(report.low_confidence_flags) + list(report.disagreement_flags)
+            if flags:
+                story.append(Paragraph("Flags", styles["Heading2"]))
+                for fl in flags:
+                    story.append(Paragraph(fl, styles["Normal"]))
+
+            story.append(Spacer(1, 0.3 * 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("pdf build failed: %s", e)
+            return None
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pytest tests/test_pdf_report.py -v`
+Expected: both tests PASS
+
+- [ ] **Step 5: Re-run the session suite (pdf_path now populated)**
+
+Run: `pytest tests/test_session.py -v`
+Expected: all PASS (now `finish_session` returns a real `pdf_path`).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add formscout/agents/pdf_report.py tests/test_pdf_report.py
+git commit -m "feat: add PdfReportAgent — branded ReportLab session PDF"
+```
+
+---
+
+## Task 7: Wire the session UI in `app.py`
+
+**Files:**
+- Modify: `app.py` (`process_video`, `build_app`, event wiring)
+
+This task is verified by running the app (Gradio event wiring is not unit-tested; the
+orchestration it calls is already covered by `tests/test_session.py`).
+
+- [ ] **Step 1: Import the session module**
+
+In `app.py`, add to the imports block (after `from formscout.startup import ensure_checkpoints`):
+
+```python
+from formscout import session as session_mod
+```
+
+- [ ] **Step 2: Refactor `process_video` to accumulate into a session**
+
+Replace the entire `process_video` function (lines ~51-105) with a version that takes and
+returns the session, appends an entry on success, and builds the "Session so far" table.
+Replace from `def process_video(` through its final `return ...` with:
+
+```python
+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."""
+    if not video_path:
+        return (
+            session_state, _render_empty_state(), "Upload a video to begin analysis.",
+            "", "", None, "", _render_session_table(session_state),
+            gr.update(visible=False), gr.update(visible=False),
+        )
+
+    if session_state is None:
+        session_state = session_mod.new_session()
+
+    director = Director()
+    state = director.run(video_path, test_name=test_name, side=side, model_key=model_key)
+
+    score_html = _render_empty_state()
+    score_details = ""
+
+    if state.features:
+        result = score_test(state.features)
+        judge = state.judge
+        if judge and judge.score is not None:
+            score_html = _render_score_card(judge.score, judge.confidence, judge.needs_human)
+            score_details = _render_score_details_judge(judge, result, state.features)
+        elif judge and judge.needs_human:
+            score_html = _render_score_card(0, 0, True)
+            score_details = f"### Needs Clinician Review\n{judge.rationale}"
+        else:
+            score_html = _render_score_card(result.score, result.confidence, result.needs_human)
+            score_details = _render_score_details(result, state.features)
+
+        # Accumulate into the session (only when we have a real analysis)
+        if state.ingest and state.pose2d and state.judge:
+            draw_trails = "trails" in {lbl.lower().replace(" ", "_") for lbl in (layers or [])}
+            try:
+                session_mod.add_analysis(
+                    session_state, ingest=state.ingest, pose2d=state.pose2d,
+                    features=state.features, judge=state.judge,
+                    test_name=test_name, side=side, draw_trails=draw_trails,
+                )
+            except Exception as e:
+                state.warnings.append(f"session accumulation failed: {e}")
+
+    pipeline_md = _render_pipeline_status(state)
+    alerts = _render_alerts(state)
+
+    overlay_path = None
+    vel_summary = ""
+    layer_set = {lbl.lower().replace(" ", "_") for lbl in (layers or [])}
+    if layer_set and state.ingest and state.pose2d:
+        try:
+            from formscout.agents.visualizer import PoseVisualizer, build_velocity_summary
+            vis = PoseVisualizer()
+            with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as f:
+                out_path = f.name
+            overlay_path = vis.render_video(state.ingest, state.pose2d, layer_set, out_path)
+            if overlay_path:
+                vel_summary = build_velocity_summary(state.pose2d.keypoints, vis.last_velocities)
+        except Exception as e:
+            alerts = (alerts or "") + f"\n⚠️ Visualizer error: {e}"
+
+    has_entries = bool(session_state and session_state.entries)
+    return (
+        session_state, score_html, pipeline_md, score_details, alerts,
+        overlay_path, vel_summary, _render_session_table(session_state),
+        gr.update(visible=has_entries), gr.update(visible=has_entries),
+    )
+```
+
+- [ ] **Step 3: Add the session-table renderer and finish handler**
+
+In `app.py`, add these two functions just before `def build_app()`:
+
+```python
+def _render_session_table(session_state) -> str:
+    """Render the accumulated 'Session so far' table as markdown."""
+    if not session_state or not session_state.entries:
+        return "*No clips analysed yet.*"
+    lines = ["| Test | Side | Score | Status |", "|---|---|---|---|"]
+    for e in session_state.entries:
+        test = e.test_name.replace("_", " ").title()
+        side = e.side if e.side in ("left", "right") else "—"
+        if e.needs_human:
+            score, status = "—", "⚠️ Clinician review"
+        else:
+            score, status = f"{e.score}/3", "✓ scored"
+        lines.append(f"| {test} | {side} | {score} | {status} |")
+    return "\n".join(lines)
+
+
+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)
+
+    report, pdf_path = session_mod.finish_session(session_state)
+    if report is None:
+        return ("⚠️ Nothing to report.", None, None)
+
+    if report.composite is not None:
+        summary = [f"## Composite: {report.composite} / 21"]
+    else:
+        n = len(session_state.entries)
+        summary = [f"## Composite: Incomplete — {n}/7 tests scored",
+                   "*(One or more tests need clinician review or were unscored.)*"]
+
+    if report.asymmetries:
+        summary.append("\n### Asymmetries")
+        for a in report.asymmetries:
+            test = a["test"].replace("_", " ").title()
+            summary.append(f"- **{test}:** L={a['left_score']} R={a['right_score']} (Δ {a['delta']})")
+
+    flags = list(report.low_confidence_flags) + list(report.disagreement_flags)
+    if flags:
+        summary.append("\n### Flags")
+        for fl in flags:
+            summary.append(f"- {fl}")
+
+    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
+```
+
+Also add `import os` to the top of `app.py` if not already present (it currently imports only
+`tempfile` and `gradio`). Add after `import tempfile`:
+
+```python
+import os
+```
+
+- [ ] **Step 4: Add the session state, buttons, and outputs to `build_app`**
+
+In `build_app`, inside the `with gr.Blocks(...) as app:` block, immediately after the line
+`with gr.Blocks(title="FormScout — FMS Screening Aid") as app:` add:
+
+```python
+        session_state = gr.State(None)
+```
+
+Then, in the left input column, replace the single submit button block:
+
+```python
+                submit_btn = gr.Button(
+                    "🎯 Score Movement",
+                    variant="primary",
+                    size="lg",
+                )
+```
+
+with:
+
+```python
+                submit_btn = gr.Button(
+                    "🎯 Score Movement",
+                    variant="primary",
+                    size="lg",
+                )
+                with gr.Row():
+                    new_clip_btn = gr.Button("➕ Analyse new clip", visible=False)
+                    finish_btn = gr.Button("✅ Finish & generate PDF",
+                                           variant="primary", visible=False)
+```
+
+In the right results column, add a "Session" tab and a finish-output area. Inside `with gr.Tabs():`
+add a new tab after the "🎬 Overlay Video" tab:
+
+```python
+                    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)
+                        md_file = gr.File(label="Analysis Log (Markdown)", visible=True)
+```
+
+- [ ] **Step 5: Update event wiring**
+
+Replace the `_map_inputs` function and `submit_btn.click(...)` block at the bottom of `build_app`
+with:
+
+```python
+        def _map_inputs(video, test_display_name, side_display, pose_model_key, overlay_layers, sess):
+            """Map UI display values to internal values and accumulate into the session."""
+            test_map = {name: val for name, val in FMS_TESTS}
+            test_name = test_map.get(test_display_name, "deep_squat")
+            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)
+
+        submit_btn.click(
+            fn=_map_inputs,
+            inputs=[video_input, test_dropdown, side_dropdown, pose_model_dropdown,
+                    overlay_layers, session_state],
+            outputs=[session_state, score_html, pipeline_md, score_details, alerts_md,
+                     overlay_video, velocity_md, session_table, new_clip_btn, finish_btn],
+        )
+
+        def _new_clip():
+            """Clear inputs for the next clip; keep the session intact."""
+            return None, _render_empty_state(), ""
+
+        new_clip_btn.click(
+            fn=_new_clip,
+            inputs=[],
+            outputs=[video_input, score_html, score_details],
+        )
+
+        finish_btn.click(
+            fn=_finish_session,
+            inputs=[session_state],
+            outputs=[finish_summary, pdf_file, md_file],
+        )
+```
+
+- [ ] **Step 6: Verify the full test suite still passes**
+
+Run: `pytest tests/ -q`
+Expected: all tests pass except the single pre-existing known failure documented in CLAUDE.md
+(`test_unimplemented_test_returns_low_confidence`). No new failures.
+
+- [ ] **Step 7: Manually verify the app**
+
+Run: `python3 app.py`
+Then in the browser:
+1. Upload a clip, pick a test, click **Score Movement** → score card appears; the **Session** tab
+   shows one row; the two new buttons appear.
+2. Click **➕ Analyse new clip** → the video input clears, the session row persists.
+3. Analyse a second test → a second row appears.
+4. Click **✅ Finish & generate PDF** → the Session tab shows the composite summary and a
+   downloadable PDF (open it: disclaimer top + bottom, per-test blocks with key-frame images,
+   composite or "Incomplete"). The Markdown log is also downloadable.
+
+Expected: all four steps work; PDF opens and contains the disclaimer, composite, and per-test sections.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add app.py
+git commit -m "feat: accumulate FMS clips into a session with composite report + PDF export"
+```
+
+---
+
+## Task 8: Update docs
+
+**Files:**
+- Modify: `CLAUDE.md` (Build phases / status)
+- Modify: `MODEL_BUDGET.md` (no param change — note PDF agent adds 0 params, for completeness)
+
+- [ ] **Step 1: Update the Phase 4 line in CLAUDE.md**
+
+In `CLAUDE.md`, in the "Build phases" section, update the Phase 4 line from:
+
+```
+4. **Phase 4 — Polish + ship:** Custom Svelte UI components, PDF export, agent trace to Hub, blog post. (Overlay video already done via `PoseVisualizer`.)
+```
+
+to:
+
+```
+4. **Phase 4 — Polish + ship:** Custom Svelte UI components, agent trace to Hub, blog post. (Overlay video done via `PoseVisualizer`; full 7-test session + PDF export done via `formscout/session.py` + `PdfReportAgent`.)
+```
+
+- [ ] **Step 2: Note the PDF agent in the architecture section**
+
+In `CLAUDE.md`, under "### Rubric scorers" or near the ReportAgent description, this is optional
+context; no required change. Skip if no natural home.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CLAUDE.md
+git commit -m "docs: mark full FMS session + PDF export complete in build phases"
+```
+
+---
+
+## Self-Review Notes (already applied)
+
+- **Spec coverage:** session accumulation (Task 5), two-button UX (Task 7), on-disk MD/JSON/keyframes (Task 5), key-frame from `features.timing` (Tasks 3–5), ReportLab PDF top/bottom disclaimer + composite + per-test + asymmetry + flags (Task 6), `SessionEntry` type (Task 2), `ReportAgent` reuse (Task 5 `finish_session`), composite-null-on-needs-human (Task 5 test), error tolerance / never-raise (Tasks 4–6). All covered.
+- **Type consistency:** `SessionEntry` field names are identical across Tasks 2, 5, 6, 7. `finish_session` returns `(ReportResult | None, str | None)` and is consumed that way in Task 7. `render_frame(ingest, pose2d, frame_idx, layers, caption, out_png)` signature matches its callers.
+- **No placeholders:** every code step shows complete code; every run step states the exact command + expected outcome.

docs/superpowers/specs/2026-06-13-full-fms-session-pdf-design.md

@@ -0,0 +1,154 @@
+# Full FMS Session + PDF Report — Design
+
+**Date:** 2026-06-13
+**Status:** Approved (brainstorming) — pending implementation plan
+**Owner:** FormScout
+**Related:** `formscout/agents/report.py`, `formscout/agents/visualizer.py`, `formscout/agents/biomechanics.py`, `app.py`, `formscout/types.py`
+
+## Problem
+
+FormScout today scores **one** FMS test per upload. A real Functional Movement Screen is **all 7 tests** producing a single **composite 0–21** with asymmetry flags. `ReportAgent` and `ReportResult.composite` already support a multi-test report, but the UI never accumulates more than one test, and `ReportResult.pdf_path` is a hardcoded `None` stub.
+
+This feature turns the one-clip scorer into a **screening session**: each analyzed clip accumulates; a "Finish" action produces the composite report plus a downloadable, brand-consistent **PDF**. Each clip's worst-moment frame is captured as an annotated still embedded in both an on-disk log and the PDF.
+
+## Goals
+
+- Accumulate multiple analyzed clips into one session, then emit a composite 0–21 report.
+- Generate a clinician/client-facing **PDF** handout (ReportLab) with scores, rationale, asymmetries, key-frame images, and the safety disclaimer.
+- Capture and annotate the **worst-moment frame** per test (the governing/peak frame already computed by `BiomechanicsAgent`).
+- Persist each analysis incrementally to disk (`session.json`, `analysis.md`, key-frame PNGs) until "Finish" is clicked.
+
+## Non-goals (YAGNI)
+
+- No cross-restart session reload — the session lives in `gr.State` + a temp dir for the browser session.
+- No PDF styling beyond a clean branded layout (no HTML/CSS engine; ReportLab only).
+- No RAG / exemplar-clip citations (separate future spec).
+- No changes to the scoring pipeline, rubric functions, or Director flow.
+
+## UX
+
+The current one-clip-at-a-time flow is preserved. Two new buttons appear after an analysis completes:
+
+- **➕ Analyse new clip** — clears the video/test inputs for the next upload; **keeps** the session.
+- **✅ Finish & generate PDF** — runs the report + PDF over everything accumulated so far.
+
+After each analysis, a **"Session so far"** table updates: `test · side · score · status`. Finish renders an on-screen composite scorecard + asymmetry summary and exposes the PDF (and `analysis.md`) via `gr.File` for download.
+
+Guard: Finish with zero analyses → warning, no PDF.
+
+## Components
+
+### 1. Session state + on-disk store
+
+A per-session temp directory `<tmpdir>/formscout_sessions/<session_id>/`:
+
+- `session.json` — structured list of entries; **source of truth** for the PDF.
+- `analysis.md` — human-readable log, appended after each clip.
+- `keyframes/<test_name>_<side>.png` — annotated worst-frame stills.
+
+Session identity lives in a `gr.State`. Each entry carries:
+
+- `test_name`, `side`, `score` (judge score, else rubric), `needs_human`
+- `rationale`, `compensation_tags`, `corrective_hint`
+- key measurements (selected `angles` / `alignments`)
+- `confidence`, `view` (`"2d"`/`"3d"`)
+- `keyframe_path`
+- the `movement` / `features` / `rubric_score` / `judge` objects that `ReportAgent.run()` consumes
+
+Persistence lasts until Finish; files are kept afterward for download. Cross-restart cleanup is best-effort and out of scope.
+
+### 2. Key-frame capture
+
+New method on `PoseVisualizer`:
+
+```python
+def render_frame(self, ingest, pose2d, frame_idx: int,
+                 layers: set[str], caption: str, out_png: str) -> str | None
+```
+
+- `frame_idx` comes from `features.timing`, which already stores the governing frame per test:
+  `deep_squat → deepest_frame`, `hurdle_step → peak_step_frame`,
+  `inline_lunge → deepest_lunge_frame`, `shoulder_mobility → measure_frame`,
+  `active_slr → peak_raise_frame`.
+- `trunk_stability_pushup` and `rotary_stability` currently store only counts in `timing`. Add the worst-sag-frame and peak-extension-frame index to their `timing` dicts (one-line change in each `BiomechanicsAgent` method).
+- Reuses `_draw_skeleton` (+ optional `_draw_trails`) on the single frame, overlays a caption naming the worst compensation, writes a PNG.
+- Returns `None` on any failure — never raises, never blocks the entry.
+
+The "worst compensation" caption is derived from `judge.compensation_tags` (preferred) or the failed `alignments` (fallback).
+
+### 3. PDF generator
+
+New module `formscout/agents/pdf_report.py`:
+
+```python
+class PdfReportAgent:
+    def run(self, report_result: ReportResult,
+            entries: list[SessionEntry], session_dir: str) -> str | None
+```
+
+Uses **ReportLab** (pure-Python, no system deps — safe on HF Spaces/ZeroGPU). Layout:
+
+- Safety disclaimer banner at **top and bottom** (mirrors the UI invariant).
+- Title/brand header + date.
+- Composite **0–21** badge, or "Incomplete — N/7 tests scored" when `composite is None`.
+- Per-test block: score, rationale, key measurements, compensation tags, corrective hint, the annotated key-frame image, asymmetry delta (bilateral).
+- Flags section: low-confidence, rubric↔judge disagreement, needs-human.
+- Populates `ReportResult.pdf_path`.
+
+Returns the PDF path, or `None` on failure (UI surfaces the error and keeps the session for retry). Image embedding tolerates a missing/`None` `keyframe_path` with a placeholder line.
+
+### 4. ReportAgent reuse
+
+At Finish, build the entry list and call the existing `ReportAgent.run()` for composite + asymmetries + flags. The bilateral lower-score + asymmetry-delta logic and the null-composite rule already exist and are not rewritten. A small adapter converts `SessionEntry` objects to the dict schema `ReportAgent.run()` expects (or `ReportAgent` gains overload tolerance — implementer's choice, keep it minimal).
+
+### 5. Types
+
+Add a `SessionEntry` frozen dataclass to `formscout/types.py` (consistent with the "every agent I/O is a typed dataclass" standard), including `keyframe_path: str | None`. Populate the existing `ReportResult.pdf_path` (and optionally `overlay_video_path`). No other type changes.
+
+### 6. UI (`app.py`)
+
+- Add a `gr.State` holding the session (id + entries).
+- After each analysis: render the scorecard as today, append the entry, write `session.json`/`analysis.md`/keyframe PNG, refresh the "Session so far" table, and reveal the two buttons.
+- **Analyse new clip**: reset the video/test/side inputs; keep session state.
+- **Finish & generate PDF**: `ReportAgent.run` → `PdfReportAgent.run` → display composite + asymmetry summary + `gr.File` downloads (PDF + `analysis.md`).
+- Guard: Finish with zero analyses → warning.
+
+## Data flow
+
+```
+upload → Director.run → score
+       → build SessionEntry (+ render_frame keyframe png)
+       → append to gr.State + write session.json / analysis.md / keyframe png
+       → refresh "Session so far" table
+
+Finish → ReportAgent.run(entries) → composite / asymmetries / flags
+       → PdfReportAgent.run(...) → pdf_path
+       → on-screen composite + gr.File (PDF, analysis.md)
+```
+
+## Error handling
+
+- Key-frame render fails → entry still saved; PDF shows an image placeholder.
+- PDF generation fails → surface the error, keep the session intact for retry.
+- `needs_human` entry → no numeric score; PDF shows "Clinician review required"; composite null.
+- Composite is `None` whenever any test is unscored or needs human review (existing rule — never show a partial 0–21 as complete).
+- All disk writes tolerate failure with a logged warning; a write failure degrades the artifact but never blocks scoring.
+
+## Testing (must run without model downloads)
+
+- `tests/test_pdf_report.py` — synthetic `ReportResult` + entries → PDF file created, non-zero size, contains the disclaimer text and composite line.
+- `tests/test_session.py` — accumulation; composite math; bilateral lower-score + asymmetry delta; null composite when one entry `needs_human`.
+- `tests/test_keyframe.py` — `render_frame` returns a real PNG path (file exists) for a synthetic frame; returns `None` gracefully on bad input.
+
+## Invariants preserved
+
+- Pipeline stays headless — no Gradio imports in agent files (`PdfReportAgent` is a pure agent; key-frame capture stays in `visualizer.py`, the existing UI-layer component).
+- Safety disclaimer present top and bottom of the PDF, mirroring the UI.
+- Pain / clearing / needs-human is never auto-scored; composite null when any test unscored.
+- New code follows the engineering standards: one public entrypoint per agent, typed dataclass I/O, `confidence`/`notes` where applicable, module docstring stating purpose/inputs/outputs/failure/params/license/gated.
+
+## Open implementation choices (left to the plan)
+
+- Exact `SessionEntry` → `ReportAgent` dict adapter shape.
+- Which measurements to surface per test in the PDF (a curated subset, not the full `angles` dump).
+- PDF assertion strategy in tests (text extraction vs. size/smoke).

formscout/agents/biomechanics.py

@@ -472,7 +472,7 @@ class BiomechanicsAgent:
         notes_parts = []
 
         # Analyze multiple frames to detect sag/lag
-        trunk_angles_over_time = []
+        trunk_sags: list[tuple[int, float]] = []  # (frame_idx, sag_px)
         for i, kps in enumerate(pose2d.keypoints):
             l_sh = _get_joint(kps, L_SHOULDER)
             r_sh = _get_joint(kps, R_SHOULDER)
@@ -482,9 +482,6 @@ class BiomechanicsAgent:
             r_ankle = _get_joint(kps, R_ANKLE)
 
             if l_sh and r_sh and l_hip and r_hip and l_ankle and r_ankle:
-                mid_sh = ((l_sh[1] + r_sh[1]) / 2,)
-                mid_hip = ((l_hip[1] + r_hip[1]) / 2,)
-                mid_ankle = ((l_ankle[1] + r_ankle[1]) / 2,)
                 # Sag = hip drops below shoulder-ankle line
                 sh_y = (l_sh[1] + r_sh[1]) / 2
                 hip_y = (l_hip[1] + r_hip[1]) / 2
@@ -492,12 +489,15 @@ class BiomechanicsAgent:
                 # In image coords: sag = hip_y > midpoint of shoulder-ankle Y
                 expected_hip_y = (sh_y + ankle_y) / 2
                 sag_px = hip_y - expected_hip_y
-                trunk_angles_over_time.append(sag_px)
-
-        if trunk_angles_over_time:
-            max_sag = max(trunk_angles_over_time)
-            variance = (sum((x - sum(trunk_angles_over_time) / len(trunk_angles_over_time))**2
-                       for x in trunk_angles_over_time) / len(trunk_angles_over_time)) ** 0.5
+                trunk_sags.append((i, sag_px))
+
+        max_sag_frame = 0
+        if trunk_sags:
+            sags = [s for _, s in trunk_sags]
+            max_sag_frame = max(trunk_sags, key=lambda t: t[1])[0]
+            mean = sum(sags) / len(sags)
+            variance = (sum((x - mean) ** 2 for x in sags) / len(sags)) ** 0.5
+            max_sag = max(sags)
             angles["max_sag_px"] = max_sag
             angles["trunk_variance_px"] = variance
             alignments["body_rigid"] = max_sag < 30 and variance < 15
@@ -523,7 +523,7 @@ class BiomechanicsAgent:
             test_name="trunk_stability_pushup", view=view, side="na",
             angles=angles, alignments=alignments,
             symmetry_delta=None,
-            timing={"n_frames_analyzed": len(trunk_angles_over_time)},
+            timing={"n_frames_analyzed": len(trunk_sags), "max_sag_frame": max_sag_frame},
             confidence=confidence,
             notes="; ".join(notes_parts) if notes_parts else "",
         )

formscout/agents/pdf_report.py

@@ -0,0 +1,115 @@
+"""
+PdfReportAgent — renders a ReportResult + session entries to a branded PDF.
+
+Input:  ReportResult, list[SessionEntry], session_dir (str)
+Output: path to the written PDF (str), or None on failure.
+Failure: returns None, never raises.
+Params: 0 (pure rendering — no model).
+License: n/a.
+Gated: no.
+"""
+from __future__ import annotations
+
+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."
+
+
+class PdfReportAgent:
+    """Assembles the screening-session PDF via ReportLab."""
+
+    def run(self, report: ReportResult, entries: list, session_dir: str) -> 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 (
+                Image, 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_report.pdf")
+        try:
+            styles = getSampleStyleSheet()
+            banner = ParagraphStyle(
+                "banner", parent=styles["Normal"], fontSize=9, textColor=colors.white,
+                backColor=colors.HexColor("#b45309"), alignment=1, borderPadding=6, spaceAfter=12,
+            )
+            story = []
+            story.append(Paragraph(f"<b>&#9888; {DISCLAIMER}</b>", banner))
+            story.append(Paragraph("FormScout — FMS Screening Report", styles["Title"]))
+
+            if report.composite is not None:
+                comp = f"Composite: <b>{report.composite} / 21</b>"
+            else:
+                comp = f"Composite: <b>Incomplete</b> — {len(entries)}/7 tests scored"
+            story.append(Paragraph(comp, styles["Heading2"]))
+            story.append(Spacer(1, 0.2 * inch))
+
+            for e in entries:
+                title = e.test_name.replace("_", " ").title()
+                if e.side in ("left", "right"):
+                    title += f" ({e.side})"
+                score_txt = "Clinician review required" if e.needs_human else f"Score: {e.score}/3"
+                story.append(Paragraph(f"<b>{title}</b> — {score_txt}", styles["Heading3"]))
+                if e.rationale:
+                    story.append(Paragraph(e.rationale, styles["Normal"]))
+                if e.compensation_tags:
+                    story.append(Paragraph("Compensations: " + ", ".join(e.compensation_tags),
+                                           styles["Normal"]))
+                if e.corrective_hint:
+                    story.append(Paragraph("Corrective: " + e.corrective_hint, styles["Normal"]))
+
+                items = list(e.measurements.items())[:6]
+                if items:
+                    rows = [[k.replace("_", " "),
+                             (f"{v:.1f}" if isinstance(v, float) else str(v))] for k, v in items]
+                    tbl = Table(rows, colWidths=[3 * inch, 1.5 * inch])
+                    tbl.setStyle(TableStyle([
+                        ("FONTSIZE", (0, 0), (-1, -1), 8),
+                        ("TEXTCOLOR", (0, 0), (-1, -1), colors.HexColor("#334155")),
+                    ]))
+                    story.append(tbl)
+
+                if e.keyframe_path and os.path.exists(e.keyframe_path):
+                    try:
+                        story.append(Image(e.keyframe_path, width=3.0 * inch, height=2.25 * inch))
+                    except Exception:
+                        story.append(Paragraph("<i>(key-frame image unavailable)</i>", styles["Normal"]))
+                else:
+                    story.append(Paragraph("<i>(key-frame image unavailable)</i>", styles["Normal"]))
+
+                story.append(Spacer(1, 0.2 * inch))
+
+            if report.asymmetries:
+                story.append(Paragraph("Asymmetries", styles["Heading2"]))
+                for a in report.asymmetries:
+                    story.append(Paragraph(
+                        f"{a['test'].replace('_', ' ').title()}: "
+                        f"L={a['left_score']} R={a['right_score']} (&#916; {a['delta']})",
+                        styles["Normal"]))
+
+            flags = list(report.low_confidence_flags) + list(report.disagreement_flags)
+            if flags:
+                story.append(Paragraph("Flags", styles["Heading2"]))
+                for fl in flags:
+                    story.append(Paragraph(fl, styles["Normal"]))
+
+            story.append(Spacer(1, 0.3 * 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("pdf build failed: %s", e)
+            return None

formscout/agents/visualizer.py

@@ -329,6 +329,53 @@ class PoseVisualizer:
             logger.warning("render_video failed: %s", e)
             return None
 
+    def render_frame(
+        self,
+        ingest,
+        pose2d,
+        frame_idx: int,
+        layers: set[str],
+        caption: str = "",
+        out_png: str | None = None,
+    ) -> str | None:
+        """Render a single annotated still (skeleton + optional trails + caption).
+
+        frame_idx is typically the governing frame from BiomechFeatures.timing.
+        Returns the PNG path on success, None on any failure. Never raises.
+        """
+        try:
+            if not (0 <= frame_idx < len(ingest.frames)) or frame_idx >= len(pose2d.keypoints):
+                return None
+
+            frame = ingest.frames[frame_idx].copy()
+            kps = pose2d.keypoints[frame_idx]
+
+            if "trails" in layers:
+                trail: dict[int, deque] = {j: deque(maxlen=TRAIL_LENGTH) for j in range(17)}
+                start = max(0, frame_idx - TRAIL_LENGTH)
+                for fi in range(start, frame_idx + 1):
+                    for j, kp in pose2d.keypoints[fi].items():
+                        if kp.get("conf", 0.0) >= CONF_THRESHOLD:
+                            trail[j].append((kp["x"], kp["y"]))
+                frame = self._draw_trails(frame, trail)
+
+            if "skeleton" in layers:
+                frame = self._draw_skeleton(frame, kps)
+
+            if caption:
+                cv2.rectangle(frame, (0, 0), (frame.shape[1], 28), (0, 0, 0), -1)
+                cv2.putText(frame, caption[:80], (8, 20), cv2.FONT_HERSHEY_SIMPLEX,
+                            0.55, (255, 255, 255), 1, cv2.LINE_AA)
+
+            if out_png is None:
+                out_png = tempfile.NamedTemporaryFile(suffix=".png", delete=False).name
+
+            ok = cv2.imwrite(out_png, frame)
+            return out_png if ok else None
+        except Exception as e:
+            logger.warning("render_frame failed: %s", e)
+            return None
+
 
 # ── Velocity summary ──────────────────────────────────────────────────────────
 

formscout/session.py

@@ -0,0 +1,194 @@
+"""
+Screening-session accumulator.
+
+Accumulates one SessionEntry per analyzed clip, persists each to a temp session
+dir (session.json + analysis.md + key-frame PNGs), and on finish builds a
+ReportResult (via ReportAgent) + a PDF (via PdfReportAgent).
+
+Pure orchestration — no Gradio imports. Disk writes tolerate failure with a
+logged warning and never block scoring.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+import uuid
+from dataclasses import dataclass, replace
+
+from formscout.rubric import score_test
+from formscout.types import MovementResult, ReportResult, SessionEntry
+
+logger = logging.getLogger(__name__)
+
+# Maps each test to the BiomechFeatures.timing key holding its governing frame.
+TIMING_KEY = {
+    "deep_squat": "deepest_frame",
+    "hurdle_step": "peak_step_frame",
+    "inline_lunge": "deepest_lunge_frame",
+    "shoulder_mobility": "measure_frame",
+    "active_slr": "peak_raise_frame",
+    "trunk_stability_pushup": "max_sag_frame",
+    "rotary_stability": "peak_extension_frame",
+}
+
+
+@dataclass
+class Session:
+    """Mutable session: an id, its temp dir, and accumulated entries."""
+    session_id: str
+    session_dir: str
+    entries: list  # list[SessionEntry]
+
+
+def new_session() -> Session:
+    sid = uuid.uuid4().hex[:12]
+    base = os.path.join(tempfile.gettempdir(), "formscout_sessions", sid)
+    try:
+        os.makedirs(os.path.join(base, "keyframes"), exist_ok=True)
+    except Exception as e:
+        logger.warning("session dir create failed: %s", e)
+    return Session(session_id=sid, session_dir=base, entries=[])
+
+
+def governing_frame_index(features) -> int | None:
+    """Return the governing frame index for this test, or None."""
+    key = TIMING_KEY.get(features.test_name)
+    if key is None:
+        return None
+    idx = features.timing.get(key)
+    return int(idx) if isinstance(idx, (int, float)) else None
+
+
+def worst_compensation_caption(judge, features) -> str:
+    """Short caption naming the worst compensation for the key-frame still."""
+    if judge and getattr(judge, "compensation_tags", None):
+        return ", ".join(judge.compensation_tags)
+    failed = [k.replace("_", " ") for k, v in features.alignments.items() if v is False]
+    return ("compensation: " + ", ".join(failed)) if failed else "key position"
+
+
+def add_analysis(session, *, ingest, pose2d, features, judge, test_name, side,
+                 draw_trails: bool = False) -> SessionEntry:
+    """Build a SessionEntry from a completed analysis, render its key-frame,
+    persist the session, append, and return the entry."""
+    movement = MovementResult(test_name=test_name, side=side, confidence=1.0)
+    rubric = score_test(features)
+
+    needs_human = bool((judge and judge.needs_human) or rubric.needs_human)
+    if needs_human:
+        score = None
+    elif judge and judge.score is not None:
+        score = judge.score
+    else:
+        score = rubric.score
+
+    keyframe_path = None
+    idx = governing_frame_index(features)
+    if idx is not None and 0 <= idx < len(pose2d.keypoints):
+        from formscout.agents.visualizer import PoseVisualizer
+        caption = (f"{test_name.replace('_', ' ').title()} "
+                   f"({side}) — {worst_compensation_caption(judge, features)}")
+        layers = {"skeleton", "trails"} if draw_trails else {"skeleton"}
+        out_png = os.path.join(session.session_dir, "keyframes", f"{test_name}_{side}.png")
+        try:
+            keyframe_path = PoseVisualizer().render_frame(ingest, pose2d, idx, layers, caption, out_png)
+        except Exception as e:
+            logger.warning("keyframe render failed: %s", e)
+
+    measurements = {}
+    measurements.update(features.angles)
+    measurements.update(features.alignments)
+
+    entry = SessionEntry(
+        test_name=test_name, side=side, score=score, needs_human=needs_human,
+        rationale=(judge.rationale if judge else rubric.rationale),
+        compensation_tags=list(judge.compensation_tags) if judge else [],
+        corrective_hint=(judge.corrective_hint if judge else ""),
+        measurements=measurements,
+        confidence=(judge.confidence if judge else rubric.confidence),
+        view=features.view,
+        keyframe_path=keyframe_path,
+        movement=movement, features=features, rubric_score=rubric, judge=judge,
+    )
+    session.entries.append(entry)
+    _persist(session)
+    return entry
+
+
+def finish_session(session) -> tuple[ReportResult | None, str | None]:
+    """Build the composite report + PDF. Returns (report, pdf_path).
+    Returns (None, None) for an empty session."""
+    if not session.entries:
+        return None, None
+
+    from formscout.agents.report import ReportAgent
+    report_inputs = [{
+        "movement": e.movement, "features": e.features,
+        "rubric_score": e.rubric_score, "judge": e.judge, "side": e.side,
+    } for e in session.entries]
+    report = ReportAgent().run(report_inputs)
+
+    pdf_path = None
+    try:
+        from formscout.agents.pdf_report import PdfReportAgent
+        pdf_path = PdfReportAgent().run(report, session.entries, session.session_dir)
+    except Exception as e:
+        logger.warning("pdf generation failed: %s", e)
+
+    report = replace(report, pdf_path=pdf_path)
+    return report, pdf_path
+
+
+# ── Persistence ───────────────────────────────────────────────────────────────
+
+def _jsonable(d: dict) -> dict:
+    out = {}
+    for k, v in d.items():
+        if isinstance(v, float):
+            out[k] = round(v, 2)
+        elif isinstance(v, (int, str, bool)) or v is None:
+            out[k] = v
+        else:
+            out[k] = str(v)
+    return out
+
+
+def _entry_display(e: SessionEntry) -> dict:
+    return {
+        "test_name": e.test_name, "side": e.side, "score": e.score,
+        "needs_human": e.needs_human, "rationale": e.rationale,
+        "compensation_tags": list(e.compensation_tags), "corrective_hint": e.corrective_hint,
+        "measurements": _jsonable(e.measurements), "confidence": round(e.confidence, 2),
+        "view": e.view, "keyframe_path": e.keyframe_path,
+    }
+
+
+def _render_markdown(session: Session) -> str:
+    lines = ["# FormScout — Session Log", ""]
+    for e in session.entries:
+        title = e.test_name.replace("_", " ").title()
+        if e.side in ("left", "right"):
+            title += f" ({e.side})"
+        score = "Clinician review required" if e.needs_human else f"{e.score}/3"
+        lines.append(f"## {title} — {score}")
+        lines.append(e.rationale or "")
+        if e.compensation_tags:
+            lines.append(f"- Compensations: {', '.join(e.compensation_tags)}")
+        if e.corrective_hint:
+            lines.append(f"- Corrective: {e.corrective_hint}")
+        if e.keyframe_path:
+            lines.append(f"- Key frame: `{e.keyframe_path}`")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _persist(session: Session) -> None:
+    try:
+        with open(os.path.join(session.session_dir, "session.json"), "w") as f:
+            json.dump([_entry_display(e) for e in session.entries], f, indent=2)
+        with open(os.path.join(session.session_dir, "analysis.md"), "w") as f:
+            f.write(_render_markdown(session))
+    except Exception as e:
+        logger.warning("session persist failed: %s", e)

formscout/types.py

@@ -142,6 +142,30 @@ class ReportResult:
     notes: str = ""
 
 
+@dataclass(frozen=True)
+class SessionEntry:
+    """One accumulated analysis in a screening session.
+
+    Display fields (test_name…keyframe_path) feed the PDF/JSON/MD artifacts;
+    the trailing typed objects (movement…judge) feed ReportAgent.run().
+    """
+    test_name: str
+    side: str
+    score: int | None
+    needs_human: bool
+    rationale: str
+    compensation_tags: list
+    corrective_hint: str
+    measurements: dict
+    confidence: float
+    view: str
+    keyframe_path: str | None
+    movement: MovementResult
+    features: BiomechFeatures
+    rubric_score: ScoreResult
+    judge: JudgeResult | None
+
+
 @dataclass
 class PipelineState:
     """Mutable state threaded through the Director."""

requirements.txt

@@ -5,6 +5,7 @@ opencv-python>=4.10
 numpy>=1.26
 scipy>=1.13
 pillow>=10.3
+reportlab>=4.0
 requests>=2.31
 pytest>=8.2
 ruff>=0.4

tests/test_biomechanics.py

@@ -96,3 +96,29 @@ class TestBiomechanicsAgent:
         result = agent.run(pose, body3d, movement)
         assert result.confidence < 0.5
         assert "not yet implemented" in result.notes
+
+
+def test_pushup_timing_has_max_sag_frame():
+    from formscout.agents.biomechanics import BiomechanicsAgent
+    from formscout.types import Pose2DResult, Body3DResult, MovementResult
+
+    # 4 frames; frame 2 has the largest hip sag (hip far below shoulder/ankle midline)
+    def kps(hip_y):
+        base = {
+            5: {"x": 200, "y": 200, "conf": 0.9},   # L shoulder
+            6: {"x": 220, "y": 200, "conf": 0.9},   # R shoulder
+            11: {"x": 300, "y": hip_y, "conf": 0.9}, # L hip
+            12: {"x": 320, "y": hip_y, "conf": 0.9}, # R hip
+            15: {"x": 400, "y": 200, "conf": 0.9},   # L ankle
+            16: {"x": 420, "y": 200, "conf": 0.9},   # R ankle
+        }
+        return base
+
+    frames = [kps(200), kps(210), kps(260), kps(205)]
+    pose = Pose2DResult(keypoints=frames, fps=30.0, confidence=0.9)
+    body3d = Body3DResult(used=False, joints_3d=[])
+    movement = MovementResult(test_name="trunk_stability_pushup", side="na", confidence=1.0)
+
+    feats = BiomechanicsAgent().run(pose, body3d, movement)
+    assert "max_sag_frame" in feats.timing
+    assert feats.timing["max_sag_frame"] == 2

tests/test_keyframe.py

@@ -0,0 +1,37 @@
+"""Tests for PoseVisualizer.render_frame — single annotated still."""
+import os
+import numpy as np
+
+from formscout.types import IngestResult, Pose2DResult
+
+
+def _ingest(n=5, h=480, w=640):
+    frames = [np.zeros((h, w, 3), dtype=np.uint8) for _ in range(n)]
+    return IngestResult(frames=frames, fps=30.0, duration=n / 30.0, n_people=1, width=w, height=h)
+
+
+def _pose(n=5):
+    kps = []
+    for i in range(n):
+        kps.append({j: {"x": float(50 + j * 25), "y": float(80 + j * 18), "conf": 0.9}
+                    for j in range(17)})
+    return Pose2DResult(keypoints=kps, fps=30.0, confidence=0.9)
+
+
+def test_render_frame_writes_png(tmp_path):
+    from formscout.agents.visualizer import PoseVisualizer
+    out = str(tmp_path / "key.png")
+    path = PoseVisualizer().render_frame(_ingest(), _pose(), frame_idx=2,
+                                         layers={"skeleton"}, caption="Deep Squat — heels elevated",
+                                         out_png=out)
+    assert path == out
+    assert os.path.exists(out)
+    assert os.path.getsize(out) > 0
+
+
+def test_render_frame_bad_index_returns_none(tmp_path):
+    from formscout.agents.visualizer import PoseVisualizer
+    out = str(tmp_path / "key.png")
+    path = PoseVisualizer().render_frame(_ingest(n=3), _pose(n=3), frame_idx=99,
+                                         layers={"skeleton"}, caption="", out_png=out)
+    assert path is None

tests/test_pdf_report.py

@@ -0,0 +1,51 @@
+"""Tests for PdfReportAgent — no GPU, no model downloads."""
+import os
+
+from formscout.types import (
+    ReportResult, SessionEntry, MovementResult, BiomechFeatures, ScoreResult, JudgeResult,
+)
+
+
+def _entry(test_name="deep_squat", score=2, needs_human=False):
+    movement = MovementResult(test_name=test_name, side="na", confidence=1.0)
+    features = BiomechFeatures(
+        test_name=test_name, view="2d", side="na",
+        angles={"left_knee_flexion_deg": 95.0}, alignments={"knees_tracking_over_feet": False},
+        symmetry_delta=None, timing={"deepest_frame": 1}, confidence=0.9,
+    )
+    rubric = ScoreResult(score=2, rationale="rubric ok", confidence=0.8)
+    judge = JudgeResult(score=None if needs_human else score, rationale="judge rationale",
+                        compensation_tags=["heels elevated"], corrective_hint="ankle mobility",
+                        confidence=0.85, needs_human=needs_human)
+    return SessionEntry(
+        test_name=test_name, side="na", score=None if needs_human else score,
+        needs_human=needs_human, rationale="judge rationale",
+        compensation_tags=["heels elevated"], corrective_hint="ankle mobility",
+        measurements={"left_knee_flexion_deg": 95.0, "knees_tracking_over_feet": False},
+        confidence=0.85, view="2d", keyframe_path=None,
+        movement=movement, features=features, rubric_score=rubric, judge=judge,
+    )
+
+
+def _report(composite=2):
+    return ReportResult(
+        per_test=[], composite=composite, asymmetries=[],
+        overlay_video_path=None, pdf_path=None,
+        low_confidence_flags=[], disagreement_flags=[],
+    )
+
+
+def test_pdf_is_created(tmp_path):
+    from formscout.agents.pdf_report import PdfReportAgent
+    path = PdfReportAgent().run(_report(2), [_entry()], str(tmp_path))
+    assert path is not None
+    assert os.path.exists(path)
+    assert os.path.getsize(path) > 1000  # a real PDF, not an empty file
+    with open(path, "rb") as f:
+        assert f.read(5) == b"%PDF-"
+
+
+def test_pdf_handles_incomplete_composite(tmp_path):
+    from formscout.agents.pdf_report import PdfReportAgent
+    path = PdfReportAgent().run(_report(None), [_entry(needs_human=True)], str(tmp_path))
+    assert path is not None and os.path.exists(path)

tests/test_session.py

@@ -0,0 +1,94 @@
+"""Tests for the FMS session accumulator — no GPU, no model downloads."""
+import numpy as np
+
+from formscout.types import (
+    IngestResult, Pose2DResult, BiomechFeatures, ScoreResult, JudgeResult,
+    MovementResult, SessionEntry,
+)
+
+
+def test_session_entry_holds_typed_objects():
+    movement = MovementResult(test_name="deep_squat", side="na", confidence=1.0)
+    features = BiomechFeatures(
+        test_name="deep_squat", view="2d", side="na",
+        angles={"left_knee_flexion_deg": 95.0}, alignments={"knees_tracking_over_feet": True},
+        symmetry_delta=None, timing={"deepest_frame": 2}, confidence=0.9,
+    )
+    rubric = ScoreResult(score=2, rationale="ok", confidence=0.8)
+    judge = JudgeResult(score=2, rationale="ok", compensation_tags=["heels elevated"],
+                        corrective_hint="ankle mobility", confidence=0.85)
+    entry = SessionEntry(
+        test_name="deep_squat", side="na", score=2, needs_human=False,
+        rationale="ok", compensation_tags=["heels elevated"], corrective_hint="ankle mobility",
+        measurements={"left_knee_flexion_deg": 95.0}, confidence=0.85, view="2d",
+        keyframe_path=None, movement=movement, features=features,
+        rubric_score=rubric, judge=judge,
+    )
+    assert entry.score == 2
+    assert entry.movement.test_name == "deep_squat"
+    assert entry.rubric_score.score == 2
+    assert entry.judge.compensation_tags == ["heels elevated"]
+
+
+def _ingest(n=5, h=480, w=640):
+    frames = [np.zeros((h, w, 3), dtype=np.uint8) for _ in range(n)]
+    return IngestResult(frames=frames, fps=30.0, duration=n / 30.0, n_people=1, width=w, height=h)
+
+
+def _pose(n=5):
+    kps = []
+    for i in range(n):
+        kps.append({j: {"x": float(50 + j * 25), "y": float(80 + j * 18), "conf": 0.9}
+                    for j in range(17)})
+    return Pose2DResult(keypoints=kps, fps=30.0, confidence=0.9)
+
+
+def _features(test_name="deep_squat", side="na", frame_key="deepest_frame"):
+    return BiomechFeatures(
+        test_name=test_name, view="2d", side=side,
+        angles={"left_knee_flexion_deg": 95.0},
+        alignments={"knees_tracking_over_feet": False},
+        symmetry_delta=None, timing={frame_key: 2}, confidence=0.9,
+    )
+
+
+def _judge(score=2, needs_human=False):
+    return JudgeResult(
+        score=None if needs_human else score, rationale="r",
+        compensation_tags=["heels elevated"], corrective_hint="ankle mobility",
+        confidence=0.85, needs_human=needs_human,
+    )
+
+
+def test_add_analysis_appends_entry_and_writes_files():
+    import os
+    from formscout import session as S
+    sess = S.new_session()
+    entry = S.add_analysis(sess, ingest=_ingest(), pose2d=_pose(),
+                           features=_features(), judge=_judge(), test_name="deep_squat", side="na")
+    assert len(sess.entries) == 1
+    assert entry.score == 2
+    assert os.path.exists(os.path.join(sess.session_dir, "session.json"))
+    assert os.path.exists(os.path.join(sess.session_dir, "analysis.md"))
+    # key-frame still written (deepest_frame=2 is valid)
+    assert entry.keyframe_path and os.path.exists(entry.keyframe_path)
+
+
+def test_finish_composite_null_when_needs_human():
+    from formscout import session as S
+    sess = S.new_session()
+    S.add_analysis(sess, ingest=_ingest(), pose2d=_pose(), features=_features(),
+                   judge=_judge(score=3), test_name="deep_squat", side="na")
+    S.add_analysis(sess, ingest=_ingest(), pose2d=_pose(),
+                   features=_features("trunk_stability_pushup", frame_key="max_sag_frame"),
+                   judge=_judge(needs_human=True), test_name="trunk_stability_pushup", side="na")
+    report, pdf_path = S.finish_session(sess)
+    assert report is not None
+    assert report.composite is None  # one test needs_human
+
+
+def test_finish_empty_session_returns_none():
+    from formscout import session as S
+    sess = S.new_session()
+    report, pdf_path = S.finish_session(sess)
+    assert report is None and pdf_path is None