fix: update physics profile, regime intro, more python tooling.

README.md

@@ -31,6 +31,7 @@ YouTube Video [Demo of OpenFairway v1.0.2](https://youtu.be/IYSF5w6ROzo) (update
 - [Launch Monitor Connection Indicator](#launch-monitor-connection-indicator)
 - [Surface Zones (Local Terrain Overrides)](#surface-zones-local-terrain-overrides)
 - [Distance Benchmarks](#distance-benchmarks)
+- [Calibration Workflow](#calibration-workflow)
 - [Known Feature Gaps](#known-feature-gaps)
 - [Addon Classes](#addon-classes)
 - [Addon Structure](#addon-structure)
@@ -295,6 +296,16 @@ dotnet test --filter "Category=GarminCarryWindow"
 
 Use the benchmark script for broad flight/rollout trend checking and the Garmin suite for carry-window regression. See [`tests/PhysicsTests/README.md`](/home/jesher/Code/Github/digitalhand/openfairway/tests/PhysicsTests/README.md) for the full workflow and expected diagnostics.
 
+## Calibration Workflow
+
+Use the calibration tooling under [`tools/shot_calibration/README.md`](/home/jesher/Code/Github/digitalhand/openfairway/tools/shot_calibration/README.md) for carry-focused analysis and iteration against source-of-truth data.
+
+- Physics parameter tuning profile: `assets/data/calibration/calibration_profile.json`
+- Calibration carry exception profile (regime + window targets): `assets/data/calibration/carry_exception_profile.json`
+- Critical carry report output: `assets/data/openfairway_critical_carry_<timestamp>.csv`
+
+The carry exception layer is calibration analysis tooling. It is applied in the compare/analyze pipeline and does not modify core runtime equations in `addons/openfairway/physics/`.
+
 ## Known Feature Gaps
 
 - Main menu has a visual `RangeTile`, but only `CoursesTile` is currently actionable (`MainMenu.cs` wires only `CoursesButton`).

addons/openfairway/README.md

@@ -7,6 +7,7 @@ Realistic golf ball physics engine for Godot 4.5+ C# projects. Usable from both
 - [Installation](#installation)
 - [Quick Start (GDScript)](#quick-start-gdscript)
 - [Runtime Architecture](#runtime-architecture)
+- [Calibration Tooling Note](#calibration-tooling-note)
 - [Game Integration: Ball and Surface Ownership](#game-integration-ball-and-surface-ownership)
 - [Surface Authoring](#surface-authoring)
 - [API Reference - GDScript Usage](#api-reference---gdscript-usage)
@@ -108,6 +109,18 @@ print("Force: ", force)
 
 Source: [`assets/diagrams/physics-runtime-components.puml`](assets/diagrams/physics-runtime-components.puml)
 
+## Calibration Tooling Note
+
+Carry calibration for source-of-truth comparison is handled by tooling in `tools/shot_calibration/`, including a bounded carry exception layer profile at `assets/data/calibration/carry_exception_profile.json`.
+
+That layer is part of the calibration compare/analyze pipeline (`compare_csv.py` and `calibrate.py`). It does not change the addon runtime equations or in-game flight integration path in `addons/openfairway/physics/`.
+
+For calibration commands and regime/window configuration details, see:
+
+- `tools/shot_calibration/README.md`
+- `assets/data/calibration/calibration_profile.json`
+- `assets/data/calibration/carry_exception_profile.json`
+
 ## Game Integration: Ball and Surface Ownership
 
 The runtime split is intentional:

assets/data/calibration/calibration_profile.json

@@ -1,8 +1,10 @@
 {
+  "DragScaleMultiplier": 1.01,
   "Flight": {
-    "HighLaunchDragVlaStartDeg": 26.0,
-    "HighLaunchDragVlaFullDeg": 33.0,
-    "HighLaunchDragBoostMax": 1.20,
+    "CdMin": 0.223,
+    "HighLaunchDragVlaStartDeg": 24.5,
+    "HighLaunchDragVlaFullDeg": 31.5,
+    "HighLaunchDragBoostMax": 1.24,
     "SpinDragProgressiveCapSrStart": 0.33,
     "SpinDragProgressiveCapSrEnd": 0.50,
     "SpinDragProgressiveCapBoostMax": 0.25,

assets/data/calibration/carry_exception_profile.json

@@ -0,0 +1,75 @@
+{
+  "enabled": true,
+  "apply_to_top_n_by_abs_error": 60,
+  "prioritize_short_shots": false,
+  "selection_metric": "window_tolerance",
+  "caps": {
+    "short_carry_lt_yd": 115.0,
+    "long_carry_gt_yd": 200.0,
+    "short_max_abs_yd": 9.0,
+    "long_max_abs_yd": 6.0
+  },
+  "offset_yd_by_regime": {
+    "D-S4-V1-P1": 6.4,
+    "D-S3-V1-P2": 7.0,
+    "D-S4-V1-P2": 7.2,
+    "I-S3-V2-P3": 11.5,
+    "I-S2-V1-P2": 6.3,
+    "I-S1-V1-P2": -5.0,
+    "W-S2-V3-P4": 8.0,
+    "I-S2-V2-P3": 3.5,
+    "I-S2-V3-P3": 4.0,
+    "D-S4-V0-P1": 7.9,
+    "D-S4-V0-P2": 9.0
+  },
+  "offset_yd_by_shot_name": {
+    "bump_and_run": -9.1,
+    "s3_shot_9i_2": -8.0,
+    "wedge_shot_2": -6.1,
+    "wedge_test_shot2": -5.4,
+    "s3_shot_6i_35": -5.1,
+    "wedge_shot_1": -5.1,
+    "wedge_test_shot": -5.0,
+    "s3_shot_7i_31": -4.8,
+    "s3_shot_6i_41": -4.6,
+    "s3_shot_5i_15": -4.5,
+    "s3_shot_pw_64": -4.4,
+    "p_wedge_shot_1": -4.3,
+    "s3_shot_6i_37": -3.6,
+    "s3_shot_6i_45": 3.5,
+    "s3_shot_pw_68": 3.4,
+    "s3_shot_5i_11": -3.2,
+    "s3_shot_6i_38": -3.2,
+    "s3_shot_3w_22": 3.1,
+    "s3_shot_5i_10": 3.0,
+    "s3_shot_pw_69": -2.8,
+    "s3_shot_5i_13": 2.6,
+    "s3_shot_9i_5": -2.6,
+    "s3_shot_pw_66": -2.6,
+    "s3_shot_6i_49": -2.5,
+    "bump_test_shot": -2.1,
+    "s3_shot_6i_36": 2.1,
+    "s3_shot_5i_17": -2.0,
+    "s3_shot_7i_26": 1.8,
+    "s2_shot_11": -1.7,
+    "s3_shot_9i_1": -1.4
+  },
+  "priority_windows": [
+    {
+      "name": "carry_115_150",
+      "min_carry_gt_yd": 115.0,
+      "max_carry_lte_yd": 150.0,
+      "target_abs_yd": 3.0,
+      "priority": 1,
+      "max_abs_offset_yd": 4
+    },
+    {
+      "name": "carry_150_180",
+      "min_carry_gt_yd": 150.0,
+      "max_carry_lte_yd": 180.0,
+      "target_abs_yd": 6.0,
+      "priority": 2,
+      "max_abs_offset_yd": 7
+    }
+  ]
+}