fix: address controller remap review feedback

docs-site/configuration.md

@@ -517,6 +517,7 @@ Important behavior:
 - `Alt+C` opens the controller config modal, where you can save the selected controller and remap actions inline.
 - Click `Learn`, then press the next fresh button, trigger, or stick direction you want to bind for that overlay action.
 - `Alt+Shift+C` opens a live debug modal showing raw axes/button values plus a ready-to-copy `buttonIndices` config block.
+- `controller.buttonIndices` is a semantic reference/legacy mapping. Changing it does not rewrite the raw numeric descriptor values already stored under `controller.bindings`.
 - Turning keyboard-only mode off clears the keyboard-only token highlight state.
 - Closing the Yomitan popup clears the temporary native text-selection fill, but keeps controller token selection active.
 
@@ -584,10 +585,26 @@ Default logical mapping:
 
 Discrete bindings may use raw button indices or raw axis directions, and analog bindings use raw axis indices with optional D-pad fallback. The `Alt+C` learn flow writes those descriptors for you, so manual edits are only needed when you want to script or copy exact mappings.
 
+If you bind a discrete action to an axis manually, include `direction`:
+
+```jsonc
+{
+  "controller": {
+    "bindings": {
+      "toggleLookup": { "kind": "axis", "axisIndex": 5, "direction": "positive" }
+    }
+  }
+}
+```
+
+Treat `controller.buttonIndices` as reference-only unless you are still using legacy semantic bindings or copying values from the debug modal. Updating `controller.buttonIndices` alone does not rewrite the hardcoded raw numeric values already present in `controller.bindings`. If you need a real remap, prefer the `Alt+C` learn flow so both the source and the descriptor shape stay correct.
+
 If you choose to bind `L2` or `R2` manually, set `triggerInputMode` to `analog` and tune `triggerDeadzone` when your controller reports triggers as analog values instead of digital pressed/not-pressed buttons. `auto` accepts either style and remains the default.
 
 If your controller reports non-standard raw button numbers, override `controller.buttonIndices` using values from the `Alt+Shift+C` debug modal.
 
+If you update this controller documentation or the generated controller examples, run `bun run docs:test` and `bun run docs:build` before merging.
+
 Tune `scrollPixelsPerSecond`, `horizontalJumpPixels`, deadzones, repeat timing, and `buttonIndices` to match your controller. See [config.example.jsonc](/config.example.jsonc) for the full generated comments for every controller field.
 
 ### Manual Card Update Shortcuts

docs-site/public/config.example.jsonc

@@ -81,43 +81,43 @@
       "rightStickPress": 10, // Raw button index used for controller R3 input.
       "leftTrigger": 6, // Raw button index used for controller L2 input.
       "rightTrigger": 7 // Raw button index used for controller R2 input.
-    }, // Button indices setting.
+    }, // Semantic button-name reference mapping used for legacy configs and debug output. Updating it does not rewrite existing raw binding descriptors.
     "bindings": {
       "toggleLookup": {
-        "kind": "button", // Discrete binding input source kind. Values: none | button | axis
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
         "buttonIndex": 0 // Raw button index captured for this discrete controller action.
-      }, // Controller binding descriptor for toggling lookup. Use Alt+C learn mode or set a raw button/axis descriptor manually.
+      }, // Controller binding descriptor for toggling lookup. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
       "closeLookup": {
-        "kind": "button", // Discrete binding input source kind. Values: none | button | axis
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
         "buttonIndex": 1 // Raw button index captured for this discrete controller action.
-      }, // Controller binding descriptor for closing lookup. Use Alt+C learn mode or set a raw button/axis descriptor manually.
+      }, // Controller binding descriptor for closing lookup. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
       "toggleKeyboardOnlyMode": {
-        "kind": "button", // Discrete binding input source kind. Values: none | button | axis
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
         "buttonIndex": 3 // Raw button index captured for this discrete controller action.
-      }, // Controller binding descriptor for toggling keyboard-only mode. Use Alt+C learn mode or set a raw button/axis descriptor manually.
+      }, // Controller binding descriptor for toggling keyboard-only mode. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
       "mineCard": {
-        "kind": "button", // Discrete binding input source kind. Values: none | button | axis
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
         "buttonIndex": 2 // Raw button index captured for this discrete controller action.
-      }, // Controller binding descriptor for mining the active card. Use Alt+C learn mode or set a raw button/axis descriptor manually.
+      }, // Controller binding descriptor for mining the active card. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
       "quitMpv": {
-        "kind": "button", // Discrete binding input source kind. Values: none | button | axis
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
         "buttonIndex": 6 // Raw button index captured for this discrete controller action.
-      }, // Controller binding descriptor for quitting mpv. Use Alt+C learn mode or set a raw button/axis descriptor manually.
+      }, // Controller binding descriptor for quitting mpv. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
       "previousAudio": {
-        "kind": "none" // Discrete binding input source kind. Values: none | button | axis
-      }, // Controller binding descriptor for previous Yomitan audio. Use Alt+C learn mode or set a raw button/axis descriptor manually.
+        "kind": "none" // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+      }, // Controller binding descriptor for previous Yomitan audio. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
       "nextAudio": {
-        "kind": "button", // Discrete binding input source kind. Values: none | button | axis
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
         "buttonIndex": 5 // Raw button index captured for this discrete controller action.
-      }, // Controller binding descriptor for next Yomitan audio. Use Alt+C learn mode or set a raw button/axis descriptor manually.
+      }, // Controller binding descriptor for next Yomitan audio. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
       "playCurrentAudio": {
-        "kind": "button", // Discrete binding input source kind. Values: none | button | axis
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
         "buttonIndex": 4 // Raw button index captured for this discrete controller action.
-      }, // Controller binding descriptor for playing the current Yomitan audio. Use Alt+C learn mode or set a raw button/axis descriptor manually.
+      }, // Controller binding descriptor for playing the current Yomitan audio. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
       "toggleMpvPause": {
-        "kind": "button", // Discrete binding input source kind. Values: none | button | axis
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
         "buttonIndex": 9 // Raw button index captured for this discrete controller action.
-      }, // Controller binding descriptor for toggling mpv play/pause. Use Alt+C learn mode or set a raw button/axis descriptor manually.
+      }, // Controller binding descriptor for toggling mpv play/pause. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
       "leftStickHorizontal": {
         "kind": "axis", // Analog binding input source kind. Values: none | axis
         "axisIndex": 0, // Raw axis index captured for this analog controller action.
@@ -138,7 +138,7 @@
         "axisIndex": 4, // Raw axis index captured for this analog controller action.
         "dpadFallback": "none" // Optional D-pad fallback used when this analog controller action should also read D-pad input. Values: none | horizontal | vertical
       } // Axis binding descriptor used for popup page jumps. Use Alt+C learn mode or set a raw axis descriptor manually.
-    } // Bindings setting.
+    } // Raw controller binding descriptors saved by Alt+C learn mode. For discrete axis bindings, kind "axis" requires axisIndex and direction.
   }, // Gamepad support for the visible overlay while keyboard-only mode is active.
 
   // ==========================================