docs: record the aim-capture blind spot - aim_fire only logs shots that passed setFire

j178 flagged it and it is real: the capture cannot show WHY a shot did not
happen (gun still hot, turret not aligned). A missing aim_fire record is
ambiguous, not a refusal. Docs only, no code change. Adds the TR_CAPTURE_AIM
row + a 'Known limitations' note to docs/env_reference.md section 8, and a
two-line pointer next to the knob in .env.example.

ModularBot_garage/.env.example

@@ -153,7 +153,9 @@
 #     TR_SURF_LOG             one line per wave-surfing decision
 #     TR_FIRE_DIAG            per-reading fire-detection tick/raw/correction
 #     TR_RECORD_WORLDSTATE    dump every observed world state to JSONL
-#     TR_CAPTURE_AIM          aim_scan/aim_fire records (gun id + bot belief)
+#     TR_CAPTURE_AIM          aim_scan/aim_fire records (gun id + bot belief).
+#                             KNOWN LIMIT: only shots that PASSED setFire are
+#                             recorded, so a gap is ambiguous - see docs/env_reference.md
 #     TR_RADAR_SCANLOG        log every radar scan tick
 #     TR_RADAR_FORCE_SPIN     force the old full-360 spin radar
 #     TR_TRACKER_PROBE        dump the enemy-tracker internals

docs/env_reference.md

@@ -616,6 +616,7 @@ Measured byte-identical on `bmPath`. Kept for experiments; leave at defaults.
 | `TR_RADAR_SCAN_LOG_PATH` | `/tmp/radar_scan_log.jsonl` | where that goes |
 | `TR_TRACKER_PROBE` | off | presence-based; per-tick enemy tracker vs server enemy count |
 | `TR_TRACKER_PROBE_PATH` | `/tmp/tracker_probe.jsonl` | where that goes |
+| `TR_CAPTURE_AIM` | off | presence-based; append `aim_scan` / `aim_fire` records — what the lead model BELIEVED (gun id, blst, age, boff, aim, turret, terr, heat, ax/ay, tof) to the same capture file as `TR_RECORD_WORLDSTATE` (needs `TR_RECORD_WORLDSTATE=1`) |
 | `TR_VBULLET_DEBUG` | off | presence-based; overlay the virtual bullets in the GUI debug graphics (see below) |
 | `TR_VBULLET_DEBUG_GUN` | selected gun | `all`/`*` for every gun, or a gun name (e.g. `Pattern`); unset = only the currently selected gun |
 | `TR_VBULLET_DEBUG_MAX` | `32` | cap on bullets drawn per tick |
@@ -633,6 +634,21 @@ selector's training signal visible. Turn it on with:
 - colour per gun is the SAME table as the turret (`vbullet_draw.gunColors`), with
   a one-line legend in the top-left corner.
 
+### Known limitations — `TR_CAPTURE_AIM` (j177)
+
+**`aim_fire` only records shots that PASSED `setFire`.** The capture is written
+from the bot's own fire call, so a shot the **server rejected or that the bot
+never issued** produces no `aim_fire` record at all.
+
+That is a real blind spot: from these records you can never answer *why* a shot
+did not happen — e.g. the gun was still hot, or the turret was not yet aligned.
+A missing `aim_fire` is ambiguous between "no target / didn't try" and "tried and
+was refused". The `aim_scan` records carry the belief state (age, boff, turret,
+heat) for every scan, so you can often *infer* the cause by looking at the scans
+that precede the gap, but the capture does not state it. Read the gaps as
+"no recorded shot", never as "the server blocked it". Closing this needs a
+pre-`setFire` gate record, which is j177+ work, not present today.
+
 The **adaptive-melee radar** has no env knobs. Its tuning lives in compile-time
 constants in `radars/adaptive_melee_radar.nim:36-50`: `MaxRadarTurnRate=45`,
 `FreshnessTicks=16`, `FreshStreakTicks=3`, `MarginDeg=20`,