Deprecate `usb.force_nkro`/`FORCE_NKRO` (#25262)

7 files changed, 36 insertions, 9 deletions

diff --git a/data/mappings/info_config.hjson b/data/mappings/info_config.hjson
index bab881583a..e4def1a4d7 100644
--- a/data/mappings/info_config.hjson
+++ b/data/mappings/info_config.hjson
@@ -64,6 +64,9 @@
     "WEAR_LEVELING_BACKING_SIZE": {"info_key": "eeprom.wear_leveling.backing_size", "value_type": "int", "to_json": false},
     "WEAR_LEVELING_LOGICAL_SIZE": {"info_key": "eeprom.wear_leveling.logical_size", "value_type": "int", "to_json": false},
 
+    // host
+    "NKRO_DEFAULT_ON": {"info_key": "host.default.nkro", "value_type": "bool"},
+
     // Layer locking
     "LAYER_LOCK_IDLE_TIMEOUT": {"info_key": "layer_lock.timeout", "value_type": "int"},
 
@@ -215,7 +218,6 @@
     "TAPPING_TOGGLE": {"info_key": "tapping.toggle", "value_type": "int"},
 
     // USB
-    "FORCE_NKRO": {"info_key": "usb.force_nkro", "value_type": "flag"},
     "USB_MAX_POWER_CONSUMPTION": {"info_key": "usb.max_power", "value_type": "int"},
     "USB_POLLING_INTERVAL_MS": {"info_key": "usb.polling_interval", "value_type": "int"},
     "USB_SUSPEND_WAKEUP_DELAY": {"info_key": "usb.suspend_wakeup_delay", "value_type": "int"},
@@ -253,6 +255,7 @@
     "PRODUCT": {"info_key": "keyboard_name", "warn_duplicate": false, "value_type": "str", "deprecated": true, "replace_with": "`keyboard_name` in info.json"},
     "PRODUCT_ID": {"info_key": "usb.pid", "value_type": "hex", "deprecated": true, "replace_with": "`usb.pid` in info.json"},
     "VENDOR_ID": {"info_key": "usb.vid", "value_type": "hex", "deprecated": true, "replace_with": "`usb.vid` in info.json"},
+    "FORCE_NKRO": {"info_key": "usb.force_nkro", "value_type": "flag", "deprecated": true, "replace_with": "`host.default.nkro` in info.json"},
 
     // Items we want flagged in lint
     "VIAL_KEYBOARD_UID": {"info_key": "_invalid.vial_uid", "invalid": true},
diff --git a/data/schemas/keyboard.jsonschema b/data/schemas/keyboard.jsonschema
index 4e8bae1084..c22b0ff0da 100644
--- a/data/schemas/keyboard.jsonschema
+++ b/data/schemas/keyboard.jsonschema
@@ -443,6 +443,18 @@
                 }
             }
         },
+        "host": {
+            "type": "object",
+            "properties": {
+                "default": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "nkro": {"type": "boolean"}
+                    }
+                }
+            }
+        },
         "leader_key": {
             "type": "object",
             "properties": {
@@ -952,7 +964,11 @@
                     "$comment": "Deprecated: use device_version instead"
                 },
                 "device_version": {"$ref": "qmk.definitions.v1#/bcd_version"},
-                "force_nkro": {"type": "boolean"},
+                "force_nkro": {
+                    "type": "boolean",
+                    "$comment": "Deprecated: use host.default.nkro instead"
+
+                },
                 "pid": {"$ref": "qmk.definitions.v1#/hex_number_4d"},
                 "vid": {"$ref": "qmk.definitions.v1#/hex_number_4d"},
                 "max_power": {"$ref": "qmk.definitions.v1#/unsigned_int"},
diff --git a/docs/config_options.md b/docs/config_options.md
index e75a5b2f7e..b2a2117693 100644
--- a/docs/config_options.md
+++ b/docs/config_options.md
@@ -140,8 +140,6 @@ If you define these options you will enable the associated feature, which may in
 
 * `#define ENABLE_COMPILE_KEYCODE`
   * Enables the `QK_MAKE` keycode
-* `#define FORCE_NKRO`
-  * NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of EEPROM setting. NKRO can still be turned off but will be turned on again if the keyboard reboots.
 * `#define STRICT_LAYER_RELEASE`
   * force a key release to be evaluated using the current layer stack instead of remembering which layer it came from (used for advanced cases)
 
diff --git a/docs/features/stenography.md b/docs/features/stenography.md
index c6c2155a9a..7fd245d59a 100644
--- a/docs/features/stenography.md
+++ b/docs/features/stenography.md
@@ -8,7 +8,7 @@ The [Open Steno Project](https://www.openstenoproject.org/) has built an open-so
 
 Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar.
 
-To enable NKRO, add `NKRO_ENABLE = yes` in your `rules.mk` and make sure to press `NK_ON` to turn it on because `NKRO_ENABLE = yes` merely adds the possibility of switching to NKRO mode but it doesn't automatically switch to it. If you want to automatically switch, add `#define FORCE_NKRO` in your `config.h`.
+To enable NKRO, add `NKRO_ENABLE = yes` in your `rules.mk` and make sure to press `NK_ON` to turn it on because `NKRO_ENABLE = yes` merely adds the possibility of switching to NKRO mode but it doesn't automatically switch to it. If you want to automatically switch, add `#define NKRO_DEFAULT_ON true` in your `config.h`.
 
 You may also need to adjust your layout, either in QMK or in Plover, if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys.
 
diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md
index 0f8f680b55..a64f2992b5 100644
--- a/docs/reference_info_json.md
+++ b/docs/reference_info_json.md
@@ -274,6 +274,14 @@ Configures the [Encoder](features/encoders) feature.
                 * The number of edge transitions on both pins required to register an input.
                 * Default: `4`
 
+## Host {#host}
+
+* `host`
+    * `default`
+        * `nkro` <Badge type="info">Boolean</Badge>
+            * The default nkro state.
+            * Default: `false`
+
 ## Indicators {#indicators}
 
 Configures the [LED Indicators](features/led_indicators) feature.
@@ -818,9 +826,6 @@ Configures the [Stenography](features/stenography) feature.
     * `vid` <Badge type="info">String</Badge> <Badge>Required</Badge>
         * The USB vendor ID as a four-digit hexadecimal number.
         * Example: `"0xC1ED"`
-    * `force_nkro` <Badge type="info">Boolean</Badge>
-        * Force NKRO to be active.
-        * Default: `false`
     * `max_power` <Badge type="info">Number</Badge>
         * The maximum current draw the host should expect from the device. This does not control the actual current usage.
         * Default: `500` (500 mA)
diff --git a/quantum/eeconfig.c b/quantum/eeconfig.c
index 1e8cfd758a..f14e6ddf97 100644
--- a/quantum/eeconfig.c
+++ b/quantum/eeconfig.c
@@ -47,6 +47,10 @@ void eeconfig_init_via(void);
 void dynamic_keymap_reset(void);
 #endif // VIA_ENABLE
 
+#ifndef NKRO_DEFAULT_ON
+#    define NKRO_DEFAULT_ON false
+#endif
+
 __attribute__((weak)) void eeconfig_init_user(void) {
 #if (EECONFIG_USER_DATA_SIZE) == 0
     // Reset user EEPROM value to blank, rather than to a set value
@@ -82,7 +86,7 @@ void eeconfig_init_quantum(void) {
         .no_gui                   = false,
         .swap_grave_esc           = false,
         .swap_backslash_backspace = false,
-        .nkro                     = false,
+        .nkro                     = NKRO_DEFAULT_ON,
         .swap_lctl_lgui           = false,
         .swap_rctl_rgui           = false,
         .oneshot_enable           = true, // Enable oneshot by default
diff --git a/quantum/keyboard.c b/quantum/keyboard.c
index be51190a87..c1a6d444a5 100644
--- a/quantum/keyboard.c
+++ b/quantum/keyboard.c
@@ -509,6 +509,7 @@ void keyboard_init(void) {
     steno_init();
 #endif
 #if defined(NKRO_ENABLE) && defined(FORCE_NKRO)
+#    pragma message "FORCE_NKRO option is now deprecated - Please migrate to NKRO_DEFAULT_ON instead."
     keymap_config.nkro = 1;
     eeconfig_update_keymap(&keymap_config);
 #endif