isaac0804 · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026
diff --git a/docs/STRATEGY_DEVELOPMENT.md b/docs/STRATEGY_DEVELOPMENT.md
@@ -377,6 +377,9 @@ whoever runs it.
   dark strip where it had the ball), each robot's distance to the ball, and goals, fouls and shots on
   top. Use it for thrashing (a robot switching tactics every few ticks), a tactic stuck committed, or
   everyone chasing the ball. Friendly side only has tactic lanes (the intentions log is config_a's).
+  The dashboard draws the same lanes under the Replay tab's controls (click to seek; hover for what
+  each mark is) and live in the Live tab. Beside a replay, its Play list reads the match as
+  situations: who had the ball from which restart or regain, for how long, and how it ended.
   Thrashing in `split_shape` against `tiki_taka_plus`: robots 2-4 flip between the attack and defence
   slots about every 1.5 s, in pairs of rows at the same tick. It is not split_shape's alone: most
   strategies that split attack and defence on possession take a tactic for under 1 s and revert about

diff --git a/docs/custom_referee_gui.md b/docs/custom_referee_gui.md
@@ -19,6 +19,28 @@ pixi run python examples/demo_referee_gui_rsim.py   # then open http://localhost
 The page shows the score, current/next command, stage and time left, `designated_position`, the
 field, the active profile and an event log; a button issues each command.
 
+## Field check (camera runs)
+
+With vision from a camera (real robots or grSim) the Live tab also shows the field check
+(`utama_core/run/field_check.py`), one row per question, red / amber / green:
+
+| Row | Fails (red) when | Warns (amber) when |
+|---|---|---|
+| Camera | no vision packet for 0.5 s | |
+| Field size | ssl-vision's geometry differs from `full_field_dims` | no geometry packet yet |
+| `<colour> <id>` (each robot we drive) | never seen, lost by vision 0.5 s, or more than 0.3 m outside `field_bounds` | |
+| `<colour> <id> radio` (real only) | it answered on the radio, then stopped | it has not answered yet (the firmware may send no feedback) |
+| `<colour> <id>` (any other) | | seen inside `field_bounds` but not configured: our planners cannot see it, often a wrong ID |
+| Ball | | not seen, or outside `field_bounds` |
+
+Only the red and amber rows are listed; the green ones fold into an "N ok" line that opens on
+click. On real robots any red row forces `HALT`, whatever the command and whether or not the page is
+open; the red banner says why. Pressing Force Start while a row is red halts again at once, so
+the check is also the pre-start gate. The field is drawn as ssl-vision sees it (+x to the right),
+with everything outside `field_bounds` dimmed, so a half-field test shows which half the runner
+expects. Space halts; nothing on the keyboard starts the robots. The Kickoff and Free Kick
+buttons are hidden when the profile has no rule that sets up a restart (goal detection only).
+
 ## Commands and what robots do
 
 | Button | Command | Use | Robots |

diff --git a/docs/roadmap.md b/docs/roadmap.md
diff --git a/docs/sim_realism.md b/docs/sim_realism.md
@@ -1,7 +1,7 @@
 # Sim realism: closing the gap between rsim and real matches
 
-Status: plan, 2026-10-14 (priorities added 2026-10-16). Nothing below is built yet unless it
-says so.
+Status: plan, 2026-10-14 (priorities added 2026-10-16; Phases 0-2 are built, 2026-10-16/17).
+Nothing below is built yet unless it says so.
 
 ## Where this leads
 
@@ -89,7 +89,7 @@ friction). **Within** means kick-to-kick noise for the same robot.
 
 | Parameter | Why it matters | From official logs? | rsim today |
 |---|---|---|---|
-| Sensing-to-action latency (vision, decision, radio, motor response) | Likeliest cause of the keeper gap | Only as other teams' total reaction time: from a kick to their keeper accelerating | None: commands act on the next tick |
+| Sensing-to-action latency (vision, decision, radio, motor response) | Likeliest cause of the keeper gap | Only as other teams' total reaction time: from a kick to their keeper accelerating; for our robots, `tools/robot_calibration.py` on a recorded field test (command sent to motion seen) | None: commands act on the next tick |
 | Ball rolling deceleration (and the switch from sliding to rolling) | Pass and shot timing; keeper reaction time | Yes: fit free-rolling segments, per match (venue carpet) | Fixed in the C++ physics (`vendor/rSim`) |
 | Kick speed: between and within | How much time the keeper has; pass weight | Yes: peak ball speed after each kick, per team | Fixed |
 | Kick direction error | Wide rate (6% vs 22%) | Partly: shot miss distance, pass error relative to the receiver | None: exact |
@@ -338,6 +338,11 @@ direction SD 3° (per robot 1.5°), ball slide 2.5–4.0 then roll 0.27–0.33 m
 
 ### Phase 2: Knobs in the sim (1–2 weeks)
 
+All of these are built (2026-10-17): `SimNoise` draws each knob per match from its range, seeded
+and recorded in the replay, and reaches `run_match`, the round-robin option, `evaluate.py` and
+`pool_v1` (the v3 ranges, played as `v3_seed2` in the 2026-10-17 round-robin). A knob at zero
+reproduces the old behaviour, so results played without `--sim-noise` are unchanged.
+
 Each knob is off by default, so current results are unchanged, and each comes with a test that
 pins its effect:
 

diff --git a/docs/testing_gaps.md b/docs/testing_gaps.md
@@ -14,9 +14,13 @@ symptom. Adopting mypy/pyright is undecided given the codebase isn't typed to th
 
 **6. New rules never systematically fuzzed against real match dynamics** — partly open.
 `pushing` (closed, `a3f3795`) and `keeper_held_ball` (fired 10 times in 6 full matches) are
-confirmed live. `ball_placement_interference` has never fired live: across ~200 placements the
-longest non-placer dwell in the 0.5m stadium was 1.0s, under the rulebook's 2s grace. Not
-treated as a bug; recheck if a match produces a ≥2s linger, or build an adversarial scenario.
+confirmed live. `ball_placement_interference` has never fired in real play: across ~200
+placements the longest non-placer dwell in the 0.5m stadium was 1.0s, under the rulebook's 2s
+grace. Not treated as a bug; recheck if a real match produces a ≥2s linger, or build an
+adversarial scenario. Our own sim does reach it, so it is no longer untested:
+`tests/moments/placement_in_corner_traps_defender.json` (round-robin
+`tournament_20261017_002337`) pins a corner placement that trapped a defender inside the
+keep-out circle, and must keep passing.
 
 ## Closed (one line each)
 
@@ -56,4 +60,4 @@ treated as a bug; recheck if a match produces a ≥2s linger, or build an advers
     finish timeout (`ae6a6f3`), `ball_is_loose` ignoring a legally barred enemy near our
     defense area (`10fc89c`); and a same-team two-robot ball scrum
     (`_teammate_already_has_ball()`, `a59a8e5`). Cross-tactic convergence in general is
-    roadmap item 7.
+    the roadmap's "Cross-tactic ball convergence".
diff --git a/docs/tools.md b/docs/tools.md
@@ -112,5 +112,7 @@ described in [STRATEGY_DEVELOPMENT.md](STRATEGY_DEVELOPMENT.md).
 | `examples/demo_referee_gui_rsim.py` | `CustomReferee` with the dashboard's referee tab, over rsim |
 | `examples/demo_referee_feedback_gui.py` | The referee UI's controller-feedback panel with fake feedback, no hardware |
 | `examples/demo_exhibition_road.py` | The Exhibition Road festival demo on the 4 m x 3 m field, over rsim |
+| `examples/real_attacker_defender.py` | One attacker against one defender on real robots (or `--mode rsim`/`grsim`): field, camera half, IDs and each robot's working hardware in one config block; the Live tab's field check gates the start. Records every camera run as an SSL game log in `replays/field/`; `--calibrate attacker\|defender` plays fixed moves for measuring that robot |
+| `tools/robot_calibration.py` | A robot's numbers from a recorded field test (`replays/field/*.log`): loop delay, speed gain and acceleration per axis (the sim's move model fitted to the camera's positions), vision noise at rest and missed detections, kick speed. Writes `<log>.calibration.json`. The same log converts to a replay with `tools/convert_ssl_log.py` |
 | `examples/demo_dribbler_test.py` | One robot dribbling round a rectangle on the Exhibition Road field |
 | `examples/demo_split_shape_match.py` | Visible grSim 6v6 of `split_shape` against itself |
diff --git a/examples/demo_custom_referee.py b/examples/demo_custom_referee.py
@@ -1,3 +1,4 @@
+# ruff: noqa: E402
 """examples/demo_custom_referee.py — visual demonstration of the CustomReferee system.
 
 Runs entirely in-process (no network, no RSim binary needed). A scripted
@@ -23,6 +24,12 @@
 
 from __future__ import annotations
 
+import sys
+from pathlib import Path
+
+# Run as `pixi run python examples/<this>.py`: utama_core is not installed, so put the repo on the path.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
 import dataclasses
 import math
 import sys

diff --git a/examples/demo_dribbler_test.py b/examples/demo_dribbler_test.py
@@ -1,3 +1,4 @@
+# ruff: noqa: E402
 """examples/demo_dribbler_test.py — Test the dribbler with one robot on the Exhibition Road field.
 
 Run:
@@ -10,6 +11,12 @@
   rectangle, releasing and reacquiring the ball each segment
 """
 
+import sys
+from pathlib import Path
+
+# Run as `pixi run python examples/<this>.py`: utama_core is not installed, so put the repo on the path.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
 from utama_core.config.field_params import GREAT_EXHIBITION_FIELD_DIMS
 from utama_core.engine.abstract_strategy import AbstractStrategy
 from utama_core.engine.context import TickContext

diff --git a/examples/demo_exhibition_road.py b/examples/demo_exhibition_road.py
@@ -1,3 +1,4 @@
+# ruff: noqa: E402
 """examples/demo_exhibition_road.py — Exhibition Road Festival demo.
 
 Run:
@@ -27,6 +28,12 @@
      advance play (human auto-advance profile).
 """
 
+import sys
+from pathlib import Path
+
+# Run as `pixi run python examples/<this>.py`: utama_core is not installed, so put the repo on the path.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
 from utama_core.config.field_params import GREAT_EXHIBITION_FIELD_DIMS
 from utama_core.custom_referee import CustomReferee
 from utama_core.custom_referee.profiles.profile_loader import (

diff --git a/examples/demo_referee_feedback_gui.py b/examples/demo_referee_feedback_gui.py
@@ -1,3 +1,4 @@
+# ruff: noqa: E402
 """Preview the referee web UI controller-feedback panel without hardware.
 
 Run:
@@ -11,6 +12,12 @@
 
 from __future__ import annotations
 
+import sys
+from pathlib import Path
+
+# Run as `pixi run python examples/<this>.py`: utama_core is not installed, so put the repo on the path.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
 import argparse
 import math
 import time

diff --git a/examples/demo_referee_gui_rsim.py b/examples/demo_referee_gui_rsim.py
@@ -1,3 +1,4 @@
+# ruff: noqa: E402
 """examples/demo_referee_gui_rsim.py — CustomReferee + web GUI + StrategyRunner (RSim).
 
 Run:
@@ -26,6 +27,12 @@
   5. With the human profile, the referee stays in STOP after a goal until the operator advances play.
 """
 
+import sys
+from pathlib import Path
+
+# Run as `pixi run python examples/<this>.py`: utama_core is not installed, so put the repo on the path.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
 from utama_core.custom_referee import CustomReferee
 from utama_core.custom_referee.profiles.profile_loader import load_profile
 from utama_core.dashboard import attach_dashboard

diff --git a/examples/demo_split_shape_match.py b/examples/demo_split_shape_match.py
@@ -1,3 +1,4 @@
+# ruff: noqa: E402
 """Visible grsim 6v6: both teams run the split-shape kernel Strategy against each other.
 
 Not a test — a manual/visual smoke run for reviewing LeadAndSupportTactic /
@@ -14,6 +15,12 @@
 Open http://localhost:8080 while this is running.
 """
 
+import sys
+from pathlib import Path
+
+# Run as `pixi run python examples/<this>.py`: utama_core is not installed, so put the repo on the path.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
 import time
 
 from utama_core.custom_referee import CustomReferee