KB convention: bindings.txt grammar is a compatibility surface (player customizations must survive upgrades)

context/glass-cockpit.md

@@ -97,6 +97,23 @@ mech turning after release).  Fix: per-binding previous-value arrays (`previousP
 the #24 rule, axis edition: disconnect-while-deflected releases direct channels (Throttle
 keeps the last lever position -- freeze beats all-stop mid-fight).
 
+## CONVENTION: bindings.txt format is a COMPATIBILITY SURFACE (2026-07-24)
+Players customize `contentindings.txt` (keys, pad, joystick/HOTAS rows) and the file is
+NOT shipped in the zip (untracked -> survives extract-over-top upgrades).  That only works if
+the grammar stays stable across versions, so:
+- **Never rename or repurpose** existing verbs (`key`/`pad`/`padaxis`/`joydev`/`joyaxis`/
+  `joybutton`/`joyhat`), channel names (`Throttle`/`JoystickX`/`JoystickY`/`LeftPedal`/
+  `RightPedal`/`Turn`), pad/axis token names, or option words (`invert`/`slew`/`deflect`/
+  `set`/`deadzone`).  A parse change that rejects a previously-valid line silently breaks a
+  player's setup mid-upgrade.
+- **New features = NEW row types or NEW trailing options** (the parser already skips unknown
+  lines with a logged warning -- old builds degrade gracefully on newer files too).
+- Semantics of existing rows must stay put (e.g. deflect = spring, slew = lever, direct pad
+  axis = outside-deadzone-owns + release edge).  If a semantic MUST change, gate it behind a
+  new option word and keep the bare form as-was.
+- The BT_JOYCONFIG wizard writes only between its `# >>> BT_JOYCONFIG` markers -- keep that
+  contract so hand edits and wizard reruns coexist.
+
 ## Generic joysticks / HOTAS / pedals -- DirectInput 8 layer (2026-07-23) [T2 rig-verified; awaiting stick hardware]
 Tester ask: configure non-Xbox controllers.  **`L4JOY.cpp/.h`** (all builds, lazy-init): DI8
 enumeration of every non-XInput game device (up to 4), `c_dfDIJoystick2` polling with